Key definition set (keyboard layout) patcher for stock xv6850 - Touch Pro CDMA

- Note -
You'll probably need to know your way around a hex editor and be able to read basic C in order to make much use of this post. That's the breaks right now. Someone else might decide to make a friendly GUI to wrap things, but right now, this program isn't particularly user friendly.
If, however, you know your way around C, then you might be interested in this post. Feel free to read on if not, though don't expect a lot of help if you're not fluent in the basic prerequisites here, as this project is very much in its early stages.
Incorrect usage of this program can easily crash your phone. Please be sure to read and understand the entire posting before deciding to actually try the program out.
--
I have written a program, keypadpatch.exe, that will patch the microp keyboard tables in the stock Verizon xv6850 keyboard driver. Unlike normal keyboard remapping programs, you can create your own Fn+key combinations on keys where there were previously none. This was important for me as there are a lot of keys on the RAPH500 keyboard without Fn+key combinations, and the keyboard was missing quick access to important keys like semicolon or underscore.
The keyboard layout patcher program will modify the key definition tables in device.exe's instance of keypad.dll. The modifications are done in RAM, so they don't persist across boots. (You could re-run the patching sequence automatically at every boot to make your changes stick if you wish, once you are comfortable with a modified key definition set.) The main advantage of this is that if you happen to break something in the keyboard driver while developing a new set of key definitions, you'll just need to reboot the phone to get things back to normal as opposed to perhaps having to hard reset the device and replace a hex edited driver dll.
The keyboard layout patcher program hardcodes offsets that are specific to the xv6850 keyboard driver. Please don't try it on any other device or firmware combination other than the initial stock Verizon firmware for the RAPH500. Running keypadpatch.exe on any other device or ROM image will likely crash the phone (likely fixable by rebooting it).
The program itself is fairly rough around the edges and developing a new full key definition set is likely not for the faint of heart. Please don't ask me directly for help with making a key definition set.
The program operates in two modes. The first mode will attempt to dump out the currently active key definition array from the running keyboard driver and save it into a file called "microp" (no extension). The file will be placed in the directory within which keypadpatch.exe resides. You will get a confirmation message box if everything works in this mode of operation.
The second mode of operation will read a key definition set file called "microp" from the directory within which keypadpatch.exe resides, and then replace the key defintion array in the keyboard driver's memory image with the one from the key definition set file. If everything works, you won't see any message boxes or any other confirmation. However, if something failed, then you'll either get an appropriate error message, or if you gave keypadpatch.exe a sufficiently invalid microp file, something will probably have crashed. Use carefully at your own peril!
If there is a "microp" file in the directory where keypadpatch.exe resides, the program runs in the second mode of operation (loading a new key definition set). Otherwise, it runs in the first mode of operation (dumping the current key definition set).
Modifying a key definition set involves popping a "microp" file open in a hex editor and twiddling fields by hand right now. There is no friendly program or GUI to make things easier than that.
For the RAPH500, the key definition set is an array of 0x3A elements, each of which is described by the following structure layout:
Code:
#define MICROP_KEY_FLAG_VIRTUAL_KEY ( 0x80000000 )
typedef struct _MICROP_KEY_DEFINITION
{
//
// Virtual keys for primary button press.
//
// { MappedVK, IMEVK, RepeatVK }
//
ULONG VirtualKey[ 3 ];
//
// Secondary characters for function combinations. Set the
// MICROP_KEY_FLAG_VIRTUAL_KEY bit to indicate that the value is actually
// a virtual key code and not a character code.
//
// { Fn + key, 123-mode key, ... }
//
ULONG FunctionChar[ 11 ];
///
// Unknown.
//
ULONG KeyId[ 2 ];
//
// Callbacks to execute when the key is pressed instead of simply inserting
// a key or character code into the input stream. The addresses should be
// valid code within device.exe.
//
// [ 0 ] - Not for Fn- combos.
// [ 1 ] - ??
// [ 2 ] - Not for Fn-combos.
// [ 3 ] - ??
//
ULONG_PTR Callbacks[ 4 ];
} MICROP_KEY_DEFINITION, * PMICROP_KEY_DEFINITION;
Many of the fields of this structure don't currently have a known meaning attached to them. If you figure out what they do, perhaps through disassembly or debugging, or simply trying them out and seeing what happens, I'd appreciate it if you'd post back in this thread.
The fields that do have a particularly relevant meaning are:
- VirtualKey[0], VirtualKey[1]: These need to be set to the virtual key code (VK_* constant) for the virtual key event to generate then the particular physical key is pressed. Usually, the first two VK values are the same, but in some cases (the enter key, for example), they differ. The file \Windows\eT9.Raphael.wwe.kmap.txt may have some clues as to VK-codes for special keys on the RAPH500 (i.e. the "launch tmail.exe key"). Note that VK-codes for numeric keys (0-9) and alphabetical keys (A-Z) are simply the ASCII values for those characters (alphabetical keys always use uppercase characters). See the above link on VK_* constants for more details.
- FunctionChar[0] is the character value (not virtual key code) to generate when a particular physical key is pressed when the Fn-key is active. Normally, this value is simply the raw character code in question (e.g. 0x20 for space, 0x41 for capital A, 0x21 for !). However, if bit 0x80000000 is set, then this value appears to be treated as a virtual key code and not a character code. Using a VK-sequence might be useful if you wanted to map an Fn-key combo to, for example, soft key 1 or soft key 2. Using a character value might be useful if you want to map an Fn-key combo to, for example, semicolon. The keyboard driver takes care of injecting any necessary shift states to make a given character value appear when you provide a raw character value here. For example, setting FunctionChar[0] to 0x21 for a particular key will cause a VK_SHIFT + VK_1 key down / key up sequence to be sent to generate a ! character.
- The last four fields, "Callbacks", desire a little bit of special mention. These are function pointers into device.exe's address space for callbacks that get invoked when a key is pressed. This is how the dedicated "launch tmail.exe" key, and the Fn-Space combo to launch CommManager.exe work on the RAPH500. Setting a particular value to NULL means that the key will be injected into the normal input system instead of being handled by a function call. As a special exemption, keypadpatch.exe accepts the magical value of 0xFFFFFFFF for a particular callback pointer to mean that the currently active callback pointer in device.exe memory space should be left alone. Any other value replaces the active callback pointer in device.exe. You will generally never want to touch this value except to NULL it out for a key that you'd like to reclaim from one of those hardcoded built in shortcut keys.
As I haven't discerned all the meanings of the fields in the key definition structure, there may be additional capabilities (or limitations) here. I've only so far attempted to perform simple tasks like create an Fn-key mapping on the Z key to generate a ' character, where there was no mapping before. It is possible that some special keys might have additional hardcoded handling elsewhere in the keyboard driver and thus might not necessarily be overridable with this method.
Some of the keys in the stock key definition set don't appear to be used for the RAPH500's physical keyboard. For example, there is a "tab" key lurking, despite there being no physical key which uses that definition slot.
Download link for keypadpatch.exe + some example key definition files, one for the stock RAPH500 layout and one that maps Fn-A to -, Fn-S to ", Fn-z to ' in the start of porting something similar to the TITA100 layout to the RAPH500:
http://www.nynaeve.net/Skywing/xv6850/keypadpatch.zip
Acknowledgements:
cmonex provided some invaluable assistance with getting the ball rolling on this project.

---

- Reserved for future updates. -

---

Posted a slightly modified key definition set: http://www.nynaeve.net/Skywing/xv6850/keys2008120301.zip.
This key definition set makes the following changes:
Code:
Key New function Old function
=======================================
Fn+Z Left soft key Unassigned
Fn+X Right soft key Unassigned
Fn+S Underscore (_) Unassigned
Fn+D Tab Unassigned
Fn+C Semicolon (;) Unassigned
Mail OK/done Start tmail
Fn+Mail Ctrl* Start tmail
(* Key combinations marked with a * may not be fully working yet.)

---

Thanks skywing!
This worked great for me, the _underscore_ was especially needed.
Anything else you want me to test? gps?
I'm off work for 5 days in a row so I can play with the phone without too much fear...
_________________
VZW TP - XV6850

---

I'm still fiddling around with this, I'll probably work on some simple tools tonight to help translate the keymap files to/from a more human-readable format.
/Andrew

---

kilozebra said:
I'm still fiddling around with this, I'll probably work on some simple tools tonight to help translate the keymap files to/from a more human-readable format.
/Andrew
Click to expand...
Click to collapse
Note that the position in the key definition array isn't what controls what physical keys map to which key definiton slots. That seems to be controlled by the first value in the array (first VK identifier), according to basic tests. Let me know if you discover something more definitive about that, though.

---

Would this tool work to remap the keys if applied on a non-Verizon CDMA ROM? I'm especially looking into putting Alltel MR1 ROM release on my Verizon TP and fixing the keyboard after that.
TIA