History of the new keyboardmapping
----------------------------------

This thing just started as much of the other modifications.
Somebody (me) wasn't satisfied with the existing code.
I had used fMSX at home a lot and I didn't really fell it was necesary to change the way fMSX did his keyboard handeling. I am just one of those weird Belgian types who prefers to use a US-qwerty clavier instead of the more regular used be-latin2 azerty keyboards which are the de-facto here in Belgium.

But whenever I tried out fMSX on other Linux machines I had problems, the keyboard accept the numeric keys from the keypad, and all keys where placed very randomly. When an older MSX friend, Jean Daniels, started experimenting with Linux I tought it was a good idea to rewrite part of the fMSX keyboard handling so that he wouldn't have a hard time using it. I decided that I wanted to be able to dynamicly alter the mapping that was done from the keyboard keys to the MSX keymatrix.

Early version
-------------
After studying the original code I added the command 'keymatrix' in the fMSX command mode to change the mapping. As soon as this seemed to work I wrote the code to load and save the changed keys array. I also added an extra commandline option and placed the actual altering/saving/loading code in its own Keyboard.c file.  
When I set out to actually input a standard Belgium azerty keybinding into a new keymap file I noticed how the original code abused the XLookupKeysym() to bind stuff like the function keys, the shift keys etc.
This made it for me impossible to bind the Insert key on the clavier to the insert key in the emulated MSX. This was due to the fact that using the old method this would result in the same key being pressed as the 'c'-key.

New version
-----------
To overcome the problem stated above I rewrote the keyboard code so that now it uses the raw keyboard codes. I am well aware of the fact that now I have lost some of the flexibility introduced by the previous version. How ever I am sure that the advantages are greater than the disadvantages. (Like using the §!*$ MS-menu-key for something usefull like emulating the accent key)

New commands
------------
I added a command line option:
  -keymap <filename>
This will load the given <filename> as keymap for the fMSX emulator.

there are 3 new commands posible in fMSX command mode.
1)  keymap <filename>
This is exactly the same as the command line option keymap

2)  keymatrix <keyrow> <bitcode> <keycode>
Use this to change the maping of the keys at run time. The <keyrow> and <bitcode> determine the bit that will be set in the MSX keymatrix. The <keycode> is the number of the key pressed as given by the xev tool.

3)  savekeymap <filename>
If you have changed some keys using the keymatrix command then you will like command. It does exactly the oposite of the keymap command and will save the keymap to a file.
Make sure that <filename> is the correct filename, if the file exists it will simply be overwritten! 

Writing your own keymap file
----------------------------
If you need to make your own keymap make sure that you know what keyboard matrix your MSX-ROMS think that is connected. The ROMS included with fMSX use an MSX European version key matrix.
You can use the perl program 'make-raw-keymap.pl' to make a first version of your own keymap. Just type "make-raw-keymap.pl mymap.txt" and your first version will be saved in the mymap.txt file. You will manually have to edit this file, for example if you want to define the two shift keys to alter row 6 bit 0. 
If you want to alter the AnyX.c file you can use 'transform-2-keys.pl' to make the byte array named Keys.

Here is an extract of the MSX Technical Data Book
Keyrows 9 and 10 are the numerical keys
For the TurboR, the 'yes' and 'no' are respectively bit ? and ? on row 11
----------------------------------------------------------------------------
3.1 Key Scanning

MSX uses the key matrices as shown in Figure 5.16, Figure 5.17 and Figure 
5.17B. The key status can be obtained in real time by examining this key 
matrix and is available for reading input.

Scanning the key matrix is done by the following BIOS routine.


* SNSMAT (0141H/MAIN) ................. reads the specified line of the
					key matrix

Input:		A <-- key matrix line to be read (0 to 10)
Output: 	A <-- status of the specified line of the key matrix
		      (when pressed, the bit of the key is 0)
Function:	specifies a line of the key matrix shown in Figure 5.16,
		Figure 5.17 or Figure 5.17B and stores its status in the
		A register. The bit corresponding with the key being pressed
		is "0", and "1" for the key not being pressed.


   Figure 5.16	MSX USA version key matrix

MSB								       LSB
	7	6	5	4	3	2	1	0
    -----------------------------------------------------------------
 0  |	B   |	L   |	    |	/   |	1   |	S   |	X   |	,   |
    |-------+-------+-------+-------+-------+-------+-------+-------|
 1  |	V   |	J   |	=   |	`   |	Q   |	A   |	C   |	N   |
    |-------+-------+-------+-------+-------+-------+-------+-------|
 2  |	G   |	8   |	0   |	]   |	W   |	F   |	Z   |	M   |
    |-------+-------+-------+-------+-------+-------+-------+-------|
 3  |	T   |	I   |	~   |	;   |	2   |	D   |	U   |	\   |
    |-------+-------+-------+-------+-------+-------+-------+-------|
 4  |	6   |	K   |	P   |	'   |   3   |   R   |   7   |   H   |
    |-------+-------+-------+-------+-------+-------+-------+-------|
 5  |	5   |	0   |	9   |	[   |	4   |	E   |	Y   |	.   |
    |-------+-------+-------+-------+-------+-------+-------+-------|
 6  |	F3  |	F2  |	F1  | CODE  | CAPS  | GRAPH | CTRL  | SHIFT |
    |-------+-------+-------+-------+-------+-------+-------+-------|
 7  | RETURN| SELECT|	BS  | STOP  |  TAB  |  ESC  |	F5  |	F4  |
    |-------+-------+-------+-------+-------+-------+-------+-------|
 8  | RIGHT | DOWN  |	UP  | LEFT  |  DEL  |  INS  | HOME  | SPACE |
    -----------------------------------------------------------------

    [TEN KEY]
    -----------------------------------------------------------------
 9  |	4   |	3   |	2   |	1   |	0   | option| option| option|
    |-------+-------+-------+-------+-------+-------+-------+-------|
10  |	.   |	,   |	-   |	9   |	8   |	7   |	6   |	5   |
    -----------------------------------------------------------------


   Figure 5.17	MSX International version key matrix

MSB								       LSB
	7	6	5	4	3	2	1	0
    -----------------------------------------------------------------
 0  |	B   |	L   |deadkey|	/   |	1   |	S   |	X   |	,   |
    |-------+-------+-------+-------+-------+-------+-------+-------|
 1  |	V   |	J   |	^   |	]   |	Q   |	A   |	C   |	N   |
    |-------+-------+-------+-------+-------+-------+-------+-------|
 2  |	G   |	8   |	0   |	[   |	W   |	F   |	Z   |	M   |
    |-------+-------+-------+-------+-------+-------+-------+-------|
 3  |	T   |	I   |	~   |	;   |	2   |	D   |	U   |	\   |
    |-------+-------+-------+-------+-------+-------+-------+-------|
 4  |	6   |	K   |	P   |	:   |	3   |	R   |	7   |	H   |
    |-------+-------+-------+-------+-------+-------+-------+-------|
 5  |	5   |	0   |	9   |	@   |	4   |	E   |	Y   |	.   |
    |-------+-------+-------+-------+-------+-------+-------+-------|
 6  |	F3  |	F2  |	F1  | CODE  | CAPS  | GRAPH | CTRL  | SHIFT |
    |-------+-------+-------+-------+-------+-------+-------+-------|
 7  | RETURN| SELECT|	BS  | STOP  |  TAB  |  ESC  |	F5  |	F4  |
    |-------+-------+-------+-------+-------+-------+-------+-------|
 8  | RIGHT | DOWN  |	UP  | LEFT  |  DEL  |  INS  | HOME  | SPACE |
    -----------------------------------------------------------------

    [TEN KEY]
    -----------------------------------------------------------------
 9  |	4   |	3   |	2   |	1   |	0   | option| option| option|
    |-------+-------+-------+-------+-------+-------+-------+-------|
10  |	.   |	,   |	-   |	9   |	8   |	7   |	6   |	5   |
    -----------------------------------------------------------------


   Figure 5.17B  MSX European version key matrix

MSB								       LSB
	7	6	5	4	3	2	1	0
    -----------------------------------------------------------------
 0  |	7   |	6   |	5   |	4   |	3   |	2   |	1   |	0   |
    |-------+-------+-------+-------+-------+-------+-------+-------|
 1  |	;   |	]   |	[   |	\   |	=   |	-   |	9   |	8   |
    |-------+-------+-------+-------+-------+-------+-------+-------|
 2  |	B   |	A   | accent|	/   |	.   |	,   |	`   |	'   |
    |-------+-------+-------+-------+-------+-------+-------+-------|
 3  |	J   |	I   |	H   |	G   |	F   |	E   |	D   |	C   |
    |-------+-------+-------+-------+-------+-------+-------+-------|
 4  |	R   |	Q   |	P   |	O   |	N   |	M   |	L   |	K   |
    |-------+-------+-------+-------+-------+-------+-------+-------|
 5  |	Z   |	Y   |	X   |	W   |	V   |	U   |	T   |	S   |
    |-------+-------+-------+-------+-------+-------+-------+-------|
 6  |	F3  |	F2  |	F1  | CODE  | CAPS  | GRAPH | CTRL  | SHIFT |
    |-------+-------+-------+-------+-------+-------+-------+-------|
 7  | RETURN| SELECT|	BS  | STOP  |  TAB  |  ESC  |	F5  |	F4  |
    |-------+-------+-------+-------+-------+-------+-------+-------|
 8  | RIGHT | DOWN  |	UP  | LEFT  |  DEL  |  INS  | HOME  | SPACE |
    -----------------------------------------------------------------

    [TEN KEY]
    -----------------------------------------------------------------
 9  |	4   |	3   |	2   |	1   |	0   | option| option| option|
    |-------+-------+-------+-------+-------+-------+-------+-------|
10  |	.   |	,   |	-   |	9   |	8   |	7   |	6   |	5   |
    -----------------------------------------------------------------


----------------------------------------------------------------------------

Credits
-------
This modification was based upon 
fMSX 2.1 Copyright (C) Marat Fayzullin 1994-1999
adapted with
the fMSX Drivers for any X-terminal 2.0 by Arnold Metselaar
and the VDPCmdEngine1.0 from Alex Wulms