

                            Keyboard driver notes


Keymap converter (Linux ==> Retro)
==================================

The Retro keymap system will be very similar to Linux, with a few
improvements... Binary, not ASCII; allow any name to be given to modifier
keys; could be extended to allow more than 8 modifiers (speed penalty)...

See 'man keymaps' for full details...

Picture it as a table:
Rows = scancodes (1-127)
Columns = keymaps (0-255, for every possible combination of modifiers)


Tokens to parse:

	keymaps #-#,#-#,#		(Specifies which columns are
					actually used)

	shift, altgr, control,		Specify modifiers for the next
	alt, shiftL, shiftr,		keycode
	ctrlL, ctrlR
	plain				Only define the unmodified keycode

	keycode <scancode> = <symbol> <symbol> ...
					Define the action for each column
					(or only certain columns, if the
					above prefixes are used)

	string <symbol> = "string"	Define <symbol> to output "string"

	compose 'x' 'y' to 'z'		When Compose key is pressed...
					Typically 'x' is accent mark and
					'y' is the letter.

<symbol> can be:
	Letters: a-z, A-Z
	Numbers: zero-nine
	Anything defined by "string"


Conversion process:
	Parse file, building separate lists of keycode, string, and compose
	definitions.  Overwrite any repeats.

	Parse another file, containing overrides for things Retro does
	differently.  (ie, extended ASCII codes instead of strings)

	Write the sections of the converted file in the order the driver
	wants.

		For function calls, write out the name of the function as it
		appears in Retro.



Retro keymap format
===================

	0. Header (8 bytes, to preserve alignment)
		dd	number of keymaps actually used (ncols)
		dd	size of string table
	1. Key table: dd type, data - for every row of every column
		For strings & functions, 'data' points to the string,
		relative to the beginning of the string table. (for
		functions, the strings is the function's name under Retro)
	2. String table
		null-terminated strings
	3. Keymaps actually used
		db	#, #, #, ...			(cols[0], cols[1], ...)



Keyboard driver implementation:
===============================

Init:
	Make 3 parallel arrays:
		Scancode of each modifier key
		Columns actually used (ie, 0,1,2,4,5,6,8,9,12)
		Address of each of keymap

	Build scancode/modifier table, "compressing" it to leave out unused
	columns.  Each entry is 2 dwords (a type and a value).
	Types are: ASCII, unicode(?), string pointer, function pointer.
	For functions, do a 'search'.

	Make up extended codes (>127 or >255) for non-ASCII keys? (Instead
	of using strings, like Linux.)

Decode:
	Build bitmap of active modifiers (place in EAX)
	Search the list of keymaps for a match (SCASB/W/D)
	Lookup scancode
	If ascii or string, add to buffer
	If function, call

Modifications:
	Write a routine to change individual keymap entries at a later date,
	i.e., for functions that weren't available when the keyboard driver
	was first loaded.
