kbd-mangler

Version 0.3.0
This is the documentation for the old version of kbd-mangler (0.3) that is no longer being maintained.

Introduction
FAQ
Disclaimer
Architecture
Installation
Manglers
Invocation of Manglers
TODO
Author

Introduction

kbd-mangler is a tool to modify the keyboard behaviour at a low level in the linux kernel. Modifications are transparent for the entire system and work naturally with any console or X application.

kbd-mangler provides a high degree of flexibility and in addition to existing features it is very easy to implement any custom behaviour. See the section architecture to understand how it works.

This project is hosted at SourceForge.net
For latest downloads and other project related information visit the SourceForge.net project page:
http://sourceforge.net/projects/kbd-mangler/

FAQ

What can I use kbd-mangler for?

You can do anything with keyboard events before the kernel and the rest of the system gets a chance to interprete them.

I don't get it, can you give me an example?

I am using kbd-mangler heavily to make that part of the keyboard to the right from the <Enter> key entirely obsolete. Winkey pressed in combination with some letter keys 'simulates' the arrows and other 'obsolete' keys.
See the section Manglers for the list of current capabilities of kbd-mangler.

How do I make kbd-mangler work with my console / X application xyz?

The main advantage of kbd-mangler and one of the reasons for its existence is that it works on the level much lower than distinction between any console or X applications. It modifies the keyboard behaviour at it's very origin in the kernel.
Thus ANY program expecting keyboard input will be affected by kbd-mangler without any specific configuration regardless whether it is a console or an X application.

Is it possible to have context-dependent behaviour?

Yes, but not out of the box, at least now. You will have to implement a mangler, capable of being informed of the current context, probably by some IPC means and switch the mode of operation accordingly.

What systems will kbd-mangler run on?

It will work out of the box on Linux running kernel versions 2.6.x. Though it should be fairly simple to adapt it for other kernel versions. If you want to make this kind of contribution, you are welcome.

I am not sure if it will work on any architecture other than common x86 PC's.
The kernel patch is against the file linux/drivers/input/keyboard/atkbd.c.
If someone can comment on this, you are welcome.

What do I need to know to be able to install and use kbd-mangler?

You neet to know how to compile and install a linux kernel version 2.6.x and how to configure module loading.
Explaining how to build and install kernel is beyond this document, there are plenty resources covering this topic in depth.
Basic understanding of the divice file management on your particular system. It will need different configuration depending on whether your device files are static or under control of devfs or udev.
Basic knowledge of shell redirection mechanism is necessary to understand how to invoke manglers.

Disclaimer

This software is provided as is without any warranty.
I am not responsible for any damage caused by using this software.
Use it at your own risk ...

I am in NO way an experienced kernel hacker, in fact it is the first time I've touched kernel.

I haven't read any kernel HOWTO's, the necessary knowhow is obtained solely by looking at some kernel sources and googling on demand.

Thus, although it works perfectly for me, there is a probability that it is done partially the wrong way eventually violating some kernel principles.

The kernel part is reasonably small and I would appreciate review of the code by someone with REAL kernel development experience so that I can remove this paragraph and people don't get scared off.

Architecture

kbd-mangler consists of the following parts:

kbd_interceptor kernel patch.
This is a minimal patch of the file
/drivers/input/keyboard/atkbd.c allowing arbitrary kernel modules to easily:
- intercept the keyboard events.
  The intercepted event may be left without changes, modified and returned for processing or completely ignored so that kernel pretends no event has happened.
- generate arbitrary keyboard events at any time.
kbd_router kernel module
This is a kernel module utilizing the above kbd_interceptor patch. It creates two character devices to communicate with it's clients (manglers). This kernel module is intended to make the entire logic of keyboard behaviour modification to be driven by programs in user space.
kbd_router clients further called manglers.
kbd_router's clients or manglers are simple programs running in user space, reading keyboard events from a special input device file, and writing eventually modified events back to a special output device file.

kbd_router is designed so that custom manglers are extremely easy to implement and use. A few manglers implemented may be taken as examples.

Installation

patch the kernel

Apply the patch located in kbd_interceptor directory. Currently only 2.6.x kernel versions are supported.

To apply the patch do the following:

# go to your kernel source root directory cd /usr/src/linux # apply patch patch -p1 < /path/to/kbd_interceptor-VERSION.patch

rebuild and setup the new kernel as usual.
compile and install kbd_router kernel module and mangler programs

This is done by usual

./configure make make install

NOTE: make install will put the kbd_router module to /lib/modules/VERSION/misc/

NOTE: kbd_router client executables (manglers) all have the prefix kbdr_ (to be found easily)
Create the kbd_router device files

This step is a little cumbersome, I haven't figured out how to make it easier.

First you must find a free device major number.

For me I have taken the major number 56. Here is the excerpt from linux/Documentation/devices.txt:
```
      56 char        Apple Desktop Bus
                     0 = /dev/adb          ADB bus control
      Additional devices will be added to this number, all
                 starting with /dev/adb.
```
If you think this will interfere with your system, pick up another major number.

To tell the driver which major number to use the major number must be given as a parameter to insmod / modprobe, or alternatively configured via /etc/modules.conf

insmod kbd_router.ko major=<MAJOR NUMBER> or modprobe kbd_router major=<MAJOR NUMBER> After you have chosen a device major number, create two devices: mknod /dev/kbdr_read c MAJOR 0 mknod /dev/kbdr_write c MAJOR 1 where MAJOR is the selected major number. After you complete the above steps, boot your modified kernel and insert the kbd_router module you should be able to invoke manglers.


 Manglers 

Following manglers have been implemented so far.





  
     kbdr_metamode
    A particular key is chosen to be the meta key.
        (not to be confused with the META key in X-Windows keyboard
	    terminology. Meta key can be any key on the keyboard.)
	



        Further any keys on the keyboard may be configured so that
        pressing/releasing them in combination with the meta key
        will be substituted with press/release events of other arbitrary keys.
	



        The number of key mappings is unlimited.



	The meta key itself may operate in two modes, normal and
	extended. In normal mode events for the meta key itself are
	suppressed and not visible to the system.
	In extended mode meta key events are emitted only in cases
	when no other key has been pressed during the time when meta key
	was held down.

        Extended mode allows an interesting application - you can mimic
        the behaviour of halfkeyboard (http://www.halfkeyboard.com)
	



        kbdr_metamode requires path to its configuration file as a single
	argument. See the files in manglers/metamode/conf/
	for config file examples.
    
  

  
     kbdr_ascii_expander
     This is a simple ASCII only macro expander.



        For example you may wish the abbreviation 'dnd' to expand to the text
        'drag and drop' as you type. When you type 'dnd' immediately
	followed by any of the terminating characters this mangler will
	hit backspace several times to erase the word 'dnd' and then type
        'drag and drop'. Terminating characters are space,
        punctuation, etc (natural word terminators).
        



        Abbreviations and their corresponding expansion texts are specified
        through a configuration file which should be given to
        kbdr_ascii_expander as a sole argument. The number of
        abbreviation/expansion pairs is unlimited.
        



        Currently only US-ASCII keymap and charset are supported.
        



        For a sample configuration file look at
        manglers/ascii_expander/conf/sample.conf
    
  

  
      kbdr_dump  
    
        This isn't really a mangler, that is, it does not change anything.
	It prints all keyboard events on the screen and is usefull for
	debugging of other manglers.
    
  
  
  
      kbdr_hello  
    
        This is a minimal example to demonstrate what is necessary to
	implement a mangler. it swaps the Y and Z keys.
    
  

  
     kbdr_fixreturn 
    
        The only purpose of this obscure mangler is to emit the release
	of the <Enter> key. This was intended to fix the hanging
	of the <Enter> key in some situations.

	Normally you won't need this.
    
  







 Invocation of Manglers 

All manglers are designed to read keyboard events from standard input,
and write keyboard events to stdandard output. A usual mangler forwards
some events directly from stdin to stdout without changes and
modifies, generates or hides some particular set of
events.




Activating a mangler is as simple as invoking the following command:





cat /dev/kbdr_read | mangler [arguments...] > /dev/kbdr_write





You can even cascade several manglers into a single processing pipeline:





cat /dev/kbdr_read | mangler1 | mangler2 .... manglerN > /dev/kbdr_write





For example to print all keyboard events to the terminal invoke the following
command:





cat /dev/kbdr_read | kbdr_dump > /dev/kbdr_write





... but before you do anything, read the below CAREFULLY: 




 !!!!!!!!! IMPORTANT NOTE !!!!!!!!! 


kbd_router is designed so that once a mangler opens /dev/kbdr_read,
the control of keyboard event processing is COMPLETELY TAKEN OVER by the
kbd_router and the [chain of] mangler[s] being executed.




Invoking manglers in a wrong way (or trying a badly written mangler)
can result in making the keyboard partially or completely inoperable.




Here is an example how to lock your keyboard (DON'T DO THIS !!!!):



cat /dev/kbdr_read


or


cat /dev/kbdr_read | some_client




Once any of the above commands is launched the keyboard events will be dumped
to your terminal but won't cause any further effect, because nobody is
actually writing events back to /dev/kbdr_write. 



As you have noticed, both of the above have one thing in common: the pipeline
is not ending with  "> /dev/kbdr_write" 



Thus to avoid troubles the rule of thumb is:



At any given time if anyone is reading the /dev/kbdr_read file
someone should also write to the /dev/kbdr_write file.
AND, if you are invoking it from command line - the whole pipeline should
be launched by a SINGLE SHELL COMMAND.





Now when you know that you are walking on a VERY THIN ice, you should also know that if something goes wrong there is a nicely working cure:




kbd_router has a magic key combination to close /dev/kbdr_read on
it's end and return the system to the normal operation.




Thus, should your keyboard appear to be 'stolen' by kbd-mangler press
the following key combination:




 Left CTRL + Left SHIFT + Right CTRL + Right SHIFT 







 TODO 


   check if the kbd_interceptor kernel patch doesn't do anything
       evil to kernel. (HELP!) 
   check if kbd_router module doesn't do anything evil to kernel.
       (HELP!) 
   write more cool manglers (SUGGESTIONS?) 
   write some documentation for developers 




Your contribution of any kind is always welcome.

Should you have any suggestions - drop me a line.







 Author 

 Gena Batyan < gbatyan AT gmx DOT net >

kbdr_metamode	A particular key is chosen to be the meta key. (not to be confused with the META key in X-Windows keyboard terminology. Meta key can be any key on the keyboard.) Further any keys on the keyboard may be configured so that pressing/releasing them in combination with the meta key will be substituted with press/release events of other arbitrary keys. The number of key mappings is unlimited. The meta key itself may operate in two modes, normal and extended. In normal mode events for the meta key itself are suppressed and not visible to the system. In extended mode meta key events are emitted only in cases when no other key has been pressed during the time when meta key was held down. Extended mode allows an interesting application - you can mimic the behaviour of halfkeyboard (http://www.halfkeyboard.com) kbdr_metamode requires path to its configuration file as a single argument. See the files in `manglers/metamode/conf/` for config file examples.
kbdr_ascii_expander	This is a simple ASCII only macro expander. For example you may wish the abbreviation 'dnd' to expand to the text 'drag and drop' as you type. When you type 'dnd' immediately followed by any of the terminating characters this mangler will hit backspace several times to erase the word 'dnd' and then type 'drag and drop'. Terminating characters are space, punctuation, etc (natural word terminators). Abbreviations and their corresponding expansion texts are specified through a configuration file which should be given to kbdr_ascii_expander as a sole argument. The number of abbreviation/expansion pairs is unlimited. Currently only US-ASCII keymap and charset are supported. For a sample configuration file look at `manglers/ascii_expander/conf/sample.conf`
kbdr_dump	This isn't really a mangler, that is, it does not change anything. It prints all keyboard events on the screen and is usefull for debugging of other manglers.
kbdr_hello	This is a minimal example to demonstrate what is necessary to implement a mangler. it swaps the Y and Z keys.
kbdr_fixreturn	The only purpose of this obscure mangler is to emit the release of the <Enter> key. This was intended to fix the hanging of the <Enter> key in some situations. Normally you won't need this.

kbd-mangler

Table of contents

Introduction

FAQ

Disclaimer

Architecture

Installation

Manglers

Invocation of Manglers

!!!!!!!!! IMPORTANT NOTE !!!!!!!!!

Left CTRL + Left SHIFT + Right CTRL + Right SHIFT

TODO

Author