linux/drivers/input/keyboard/atkbd.c.
# go to your kernel source root directory
cd /usr/src/linux
# apply patch
patch -p1 < /path/to/kbd_interceptor-VERSION.patch
./configure
make
make install
/lib/modules/VERSION/misc/
kbdr_ (to be found easily)
56 char Apple Desktop Bus
0 = /dev/adb ADB bus control
Additional devices will be added to this number, all
starting with /dev/adb.
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 >