keymaps_keyboard_input.html

Android Porting Guide

<p>Key character maps are stored on the device as binary resources in order to reduce loading time. Key character maps have the following characteristics:</p>
<p><ul>

<li>Comments: The pound symbol (#) denotes a comment and everything after the pound symbol on a line is ignored.</li>
<li>Whitespace: All empty lines are ignored.</li>
<li>Column definitions: Column definitions follow the syntax <code>columns MODIFIERS [...]</code>, where <code>MODIFIERS</code> are defined as follows:
<table border=1 cellpadding=2 cellspacing=0>
    <tbody><tr>
        <th scope="col">Character in MODIFIERS</th>
        <th scope="col">Corresponding bit in the modifiers</th>
    </tr>
    <tr>
        <td>O</td>
        <td>no modifiers</td>
    </tr>
    <tr>
        <td>S</td>
        <td>MODIFIER_SHIFT</td>
    </tr>
    <tr>
        <td>C</td>
        <td>MODIFIER_CONTROL</td>
    </tr>
    <tr>
        <td>L</td>
        <td>MODIFIER_CAPS_LOCK</td>
    </tr>
    <tr>
        <td>A</td>
        <td>MODIFIER_ALT</td>
    </tr>
</table>
</li>
<li>Key definitions: Key definitions have the syntax <code>key SCANCODE CHARACTER [...]</code> where <code>SCANCODE</code> is a number and <code>CHARACTER</code> values are either UTF-8 characters in quotation marks (for example, "a") or a numeric value that <code>strtol</code> can parse.</li>
</ul></p>


<a name="androidKeymapKeyCharMapExample"></a><h3>Example of a Key Character Map File</h3>

<p>The following code comes from <code>android/src/device/product/generic/tuttle2.kcm</code> and represents a complete key character file:</p>
<p>The type line indicates what kind of keyboard your device implements. Possible types include:</p>
<p><ul>
<li><b>NUMERIC</b>: A numeric (12-key) keyboard.</li>
<li><b>Q14</b>: A keyboard that includes all letters but multiple letters per key.</li>
<li><b>QWERTY</b>: A keyboard with all letters and possibly numbers. This option applies to all full keyboard configurations, such as AZERTY.</li>
</ul>
</p>
<pre class="prettify">
# Copyright 2007 Google Inc.

[type=QWERTY]

# keycode   base    caps    fn      caps_fn number  display_label

A           'a'     'A'     '%'     0x00    '%'     'A'
B           'b'     'B'     '='     0x00    '='     'B'
C           'c'     'C'     '8'     0x00E7  '8'     'C'
D           'd'     'D'     '5'     0x00    '5'     'D'
E           'e'     'E'     '2'     0x0301  '2'     'E'
F           'f'     'F'     '6'     0x00A5  '6'     'F'
G           'g'     'G'     '-'     '_'     '-'     'G'
H           'h'     'H'     '['     '{'     '['     'H'
I           'i'     'I'     '$'     0x0302  '$'     'I'
J           'j'     'J'     ']'     '}'     ']'     'J'
K           'k'     'K'     '"'     '~'     '"'     'K'
L           'l'     'L'     '''     '`'     '''     'L'
M           'm'     'M'     '>'     0x00    '>'     'M'
N           'n'     'N'     '<'     0x0303  '<'     'N'
O           'o'     'O'     '('     0x00    '('     'O'
P           'p'     'P'     ')'     0x00    ')'     'P'
Q           'q'     'Q'     '*'     0x0300  '*'     'Q'
R           'r'     'R'     '3'     0x20AC  '3'     'R'
S           's'     'S'     '4'     0x00DF  '4'     'S'
T           't'     'T'     '+'     0x00A3  '+'     'T'
U           'u'     'U'     '&'     0x0308  '&'     'U'
V           'v'     'V'     '9'     '^'     '9'     'V'
W           'w'     'W'     '1'     0x00    '1'     'W'
X           'x'     'X'     '7'     0xEF00  '7'     'X'
Y           'y'     'Y'     '!'     0x00A1  '!'     'Y'
Z           'z'     'Z'     '#'     0x00    '#'     'Z'

COMMA       ','     ';'     ';'     '|'     ','     ','
PERIOD      '.'     ':'     ':'     0x2026  '.'     '.'
AT          '@'     '0'     '0'     0x2022  '0'     '@'
SLASH       '/'     '?'     '?'     '\'     '/'     '/'

SPACE       0x20    0x20    0x9     0x9     0x20    0x20
NEWLINE     0xa     0xa     0xa     0xa     0xa     0xa

# on pc keyboards
TAB         0x9     0x9     0x9     0x9     0x9     0x9
0           '0'     ')'     ')'     ')'     '0'     '0'
1           '1'     '!'     '!'     '!'     '1'     '1'
2           '2'     '@'     '@'     '@'     '2'     '2'
3           '3'     '#'     '#'     '#'     '3'     '3'
4           '4'     '$'     '$'     '$'     '4'     '4'
5           '5'     '%'     '%'     '%'     '5'     '5'
6           '6'     '^'     '^'     '^'     '6'     '6'
7           '7'     '&'     '&'     '&'     '7'     '7'
8           '8'     '*'     '*'     '*'     '8'     '8'
9           '9'     '('     '('     '('     '9'     '9'

GRAVE         '`'     '~'     '`'     '~'     '`'     '`'
MINUS         '-'     '_'     '-'     '_'     '-'     '-'
EQUALS        '='     '+'     '='     '+'     '='     '='
LEFT_BRACKET  '['     '{'     '['     '{'     '['     '['
RIGHT_BRACKET ']'     '}'     ']'     '}'     ']'     ']'
BACKSLASH     '\'     '|'     '\'     '|'     '\'     '\'
SEMICOLON     ';'     ':'     ';'     ':'     ';'     ';'
APOSTROPHE    '''     '"'     '''     '"'     '''     '''
STAR          '*'     '*'     '*'     '*'     '*'     '*'
POUND         '#'     '#'     '#'     '#'     '#'     '#'
PLUS          '+'     '+'     '+'     '+'     '+'     '+'
</pre>


<a name="androidKeymapKeyCharMapResourceBinaryFileFormat"></a><h3>Resource Binary File Format</h3>

<p>The file snippet above gets converted to the following by the <code>makekcharmap</code> tool as part of the build process. You can <code>mmap</code> this file in and share the approximately 4k of memory that it uses between processes to minimize load time.</p>
<table>
    <tbody><tr>
        <th scope="col">Offset</th>

        <th scope="col">Size (bytes)</th>
        <th scope="col">Description</th>
    </tr>
    <tr>
        <td>0x00-0x0b</td>
        <td></td>
        <td>The ascii value "keycharmap1" including the null character</td>

    </tr>
    <tr>
        <td>0x0c-0x0f</td>
        <td></td>
        <td>padding</td>
    </tr>
    <tr>
        <td>0x10-0x13</td>

        <td></td>
        <td>The number of entries in the modifiers table (COLS)</td>
    </tr>
    <tr>
        <td>0x14-0x17</td>
        <td></td>
        <td>The number of entries in the characters table (ROWS)</td>

    </tr>
    <tr>
        <td>0x18-0x1f</td>
        <td></td>
        <td>padding</td>
    </tr>
    <tr>
        <td></td>

        <td>4*COLS</td>
        <td>Modifiers table.  The modifier mask values that each of the 
            columns in the characters table correspond to.</td>
    </tr>
    <tr>
        <td></td>
        <td></td>
        <td>padding to the next 16 byte boundary</td>

    </tr>
    <tr>
        <td></td>
        <td>4*COLS*ROWS</td>
        <td>Characters table.  The modifier mask values that each of the
            columns correspond to.</td>
    </tr>
</tbody></table>


<a name="androidKeymapDriverTemplate"></a><h2>Implementing Your Own Driver (Driver Template)</h2>

<p>The following file, <code>pguide_events.c</code>, illustrates how to implement an Android keymap driver.</p>
<pre class="prettyprint">
/*
 * pguide_events.c
 *
 * ANDROID PORTING GUIDE: INPUT EVENTS DRIVER TEMPLATE
 *
 * This template is designed to an example of the functionality
 * necessary for Android to recieve input events.  The PGUIDE_EVENT
 * macros are meant as pointers indicating where to implement the
 * hardware specific code necessary for the new device.  The existence
 * of the macros is not meant to trivialize the work required, just as
 * an indication of where the work needs to be done.
 * 
 * Copyright 2007, Google Inc.
 * Based on goldfish-events.c
 *
 */

#include <linux/module.h>
#include <linux/init.h>
#include <linux/interrupt.h>
#include <linux/types.h>
#include <linux/input.h>
#include <linux/kernel.h>
#include <linux/platform_device.h>


#include <asm/irq.h>
#include <asm/io.h>



#define PGUIDE_EVENTS_INTERRUPT do{} while(0)
#define PGUIDE_EVENTS_PROBE do{} while(0)

struct event_dev {
    struct input_dev *input;
    int irq;
};

static irqreturn_t pguide_events_interrupt(int irq, void *dev_id)
{
    struct event_dev *edev = dev_id;
    unsigned type=0, code=0, value=0;

    /* Set up type, code, and value per input.h
     */
    PGUIDE_EVENTS_INTERRUPT;

    input_event(edev->input, type, code, value);
    return IRQ_HANDLED;
}

static int pguide_events_probe(struct platform_device *pdev)
{
    struct input_dev *input_dev;
    struct event_dev *edev;
    
    printk("*** pguide events probe ***\n");

    edev = kzalloc(sizeof(struct event_dev), GFP_KERNEL);
    input_dev = input_allocate_device();

    /* Setup edev->irq and do any hardware init */
    PGUIDE_EVENTS_PROBE;

    if(request_irq(edev->irq, pguide_events_interrupt, 0,
                   "pguide_events", edev) < 0) {
        goto fail;
    }
    
        /* indicate that we generate key events */
    set_bit(EV_KEY, input_dev->evbit);
    set_bit(EV_REL, input_dev->evbit);
    set_bit(EV_ABS, input_dev->evbit);

    /* indicate that we generate *any* key event */

    bitmap_fill(input_dev->keybit, KEY_MAX);
    bitmap_fill(input_dev->relbit, REL_MAX);
    bitmap_fill(input_dev->absbit, ABS_MAX);
    
    platform_set_drvdata(pdev, edev);

    input_dev->name = "pguide_events";
    input_dev->private = edev;
    input_dev->cdev.dev = &pdev->dev;
    
    input_register_device(input_dev);
    return 0;

fail:
    kfree(edev);
    input_free_device(input_dev);
    
    return -EINVAL;
}

static struct platform_driver pguide_events_driver = {
    .probe = pguide_events_probe,
    .driver = {
        .name = "pguide_events",
    },
};

static int __devinit pguide_events_init(void)
{
    return platform_driver_register(&pguide_events_driver);
}


static void __exit pguide_events_exit(void)
{
}

module_init(pguide_events_init);
module_exit(pguide_events_exit);

MODULE_DESCRIPTION("Pguide Event Device");
MODULE_LICENSE("GPL");
</pre>


<a name="androidKeymapKeyCharMapSampleImplementation"></a><h2>Sample Implementation</h2>

<p>Assume the following for the setup of a new keypad device:</p>
<pre class="prettify">
android.keylayout.partnerxx_keypad = /system/usr/keylayout/partnerxx_keypad.kl
android.keychar.partnerxx_keypad = /system/usr/keychars/partnerxx.kcm
</pre>
<p>The following example log file indicates that you have correctly registered the new keypad:</p>
<pre class="prettify">
I/EventHub( 1548): New device: path=/dev/input/event0 name=partnerxx_keypad id=0x10000 (of 0x1) index=1 fd=30
I/EventHub( 1548): new keyboard input device added, name = partnerxx_keypad
D/WindowManager( 1548): Starting input thread.
D/WindowManager( 1548): Startup complete!
I/EventHub( 1548): New keyboard: name=partnerxx_keypad 
  keymap=partnerxx_keypad.kl 
  keymapPath=/system/usr/keychars/partnerxx_keypad.kcm.bin
I/ServiceManager( 1535): ServiceManager: addService(window, 0x13610)
I/EventHub( 1548): Reporting device opened: id=0x10000, name=/dev/input/event0
I/KeyInputQueue( 1548): Device added: id=0x10000, name=partnerxx_keypad, classes=1
I/KeyInputQueue( 1548):   Keymap: partnerxx_keypad.kl
</pre>
<p>The snippet above contains artificial line breaks to maintain a print-friendly document.</p>


<p><span class="lh2"><a name="androidFooter"></a></span>

        </div>
      </div>
      <!-- end gc-pagecontent -->
    </div>
    <!-- end gooey wrapper -->
  </div>
  <!-- end codesearchresults -->
  <div id="gc-footer" dir="ltr">
    <div class="text"> &copy;2008 Google<!-- - <a href="/">Code Home</a> - <a href="http://www.google.com/accounts/TOS">Site Terms of Service</a> - <a href="http://www.google.com/privacy.html">Privacy Policy</a> - <a href="/more">Site Directory</a> --></div>
  </div>
  <!-- end gc-footer -->
</div>
<!-- end gc-containter -->
<script src="http://www.google-analytics.com/ga.js" type="text/javascript">
</script>
<script type="text/javascript">
  try {
    var pageTracker = _gat._getTracker("UA-18071-1");
    pageTracker._setAllowAnchor(true);
    pageTracker._initData();
    pageTracker._trackPageview(); 
  } catch(e) {}
</script>
<div id="jd-build-id"> v0.6 - 25 November 2008</div>
</div></div></div></body>
</html>