FD-KEYB: international keyboard BIOS enhancement for FreeDOS ============================================================ =========================================================================== FD-KEYB: enhances or replaces BIOS keyboard management to adapt it to international keyboards. Copyright (C) 2006 by Aitor SANTAMARIA_MERINO aitorsm@inicia.es Version : 2.00 Last edit: 2006-08-29 (ASM) This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. =========================================================================== 0.- INTRODUCTION ================ FD-KEYB enhances or replaces the BIOS keyboard management to adapt it to international keyboard layouts (such as German, Spanish or Japanese keyboards), thus allowing DOS to transparently use these keyboards as natively supported by BIOS. It is often called a "keyboard driver", and it also implements the DOS KEYB Multiplexer API. From now on we shall also use the word "driver", in the understanding that it is not a true DOS device driver. Besides producing characters, the driver can also be programmed to produce a large variety of other effects, such as producing characters, triggering interrupts, managing power or introducing the diacritics. The driver has been specially built from scratch to fill the FreeDOS needs for keyboard management (some code of KEYB2 was previously contributed to FreeDOS xkeyb). 0.1.- Who should use the software The software is to be used by all those worldwide users that own localized keyboards and want their keyboard to act responsively on their FreeDOS (or other DOS). It also allows keyboard reprogramming, and may be used for those that want to assign strings or other effects, or reprogram the behaviour of their keyboard. 0.2.- Compatibility In this version, the keyboard requires a PC with a DOS 2.0 or later. FD-KEYB 2.00 understands KL files on their version 1.1, and compilation files version 1.0. 0.3.- Limitations and incompatibilities The KL files must be at maximum of 3 Kb files. The driver may be incompatible with other drivers of the same style, specially the earliest versions of KEYB of DR-DOS. 0.4.- Version This is version 2.00 (final) of FD-KEYB. It understands version 1.1 of KL files, and version 1.0 of compilation files. 0.5.- Copyright Version 2.00 of this program are distributed under the GNU General Public License version 2.0. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. 0.6.- Installation FD-KEYB requires a single executable to work, which is KEYB.EXE. You would also need KL files suited to your keyboard layout, or compilation (KC files), such as KEYBOARD.SYS. (HINT: you may find packs of compilation files in the FreeDOS site, or make your own with the compiler). Place your KEYB.EXE commandline in AUTOEXEC.BAT if you want KEYB to load automatically when you boot up. Respect to the compilation files, or the KL files, they will be sought in current directory, in the directory of KEYB.EXE and through the %PATH% environment variable. 0.7.- Known bugs and reporting bugs There are no known bugs. If you find a bug, please make sure that the bug affects KEYB.EXE and not the layout you are using. If the problem is in one of the KL files you are using and not in KEYB.EXE, the resolution can be delayed as you would need to contact the developer of the KL files instead. If you want to report bugs, please fill a bug report on the FreeDOS Bugzilla: http://www.freedos.org/bugs/bugzilla/ Alternatively, write an email to Aitor SANTAMARIA MERINO aitor.sm@gmail.com 0.8.- File history FD-KEYB has been completely rewritten from scratch, although it has been written by successively replacing different parts of xkeyb in the xkeyb executable (in prototypes 1-4). This version of KEYB is completely new, and does not have any xkeyb code (although some routines written by me may be shared between the prototypes and FD-KEYB). Version 2.00 is released the 28th of August, 2006 0.9.- Acknowledgements Although developed from scratch, I am sincerely very grateful to a large number of people that have helped me. Henrique Peron for his help and bug reports. Matthias Paul for his extensive knowledge of hardware and DOS, his hints and his contributed code for the APM management commands (flushing caches). Axel Frinke, for his help with code, patience and very interesting ideas that have saved several bytes of code. T. Kabe for his ideas, valuable information (mainly about DOS/V) and testing. D. Hoehmann, for creating the original xkeyb, from which I learnt about leyboards, and for his ideas, mainly for string management. Eric Auer, for his beeping code and hints 1.- KEYB features ================= 1.1.- Commandline syntax KEYB layoutName[,[CP][,filename]] [/ID:nnn] [/E] [/9] [/I] [/Dx] [/V] [/L=m] [/NOHI] [/B] [/S] KEYB [/U] KEYB /? A keyboard layout is identified by two labels, a string label, which is mandatory (usually a two letter string, such as GR, FR or SP), and an optional numeric identifier to distinguish different variants. KEYB data is stores in a separate MCB in upper memory by default. Parameterless KEYB will show information on the currently loaded KEYB. LayoutName string identifier /ID:nnn Specifies the numeric identifier nnn filename The KL file that contains the information for the given layout, or the compilation file where the information resides. If it is omitted, then KEYBOARD.SYS is tried, alternatively .KL /E Specifies that the keyboard is an AT enhanced keyboard (this switch is incompatible with /9) /9 Specifies that int9h management services must be activated (this switch is incompatible with /E) /I Forces the installation over an already existing keyboard driver /Dx Sets the decimal separator character to x /V Verbose: prints more information /L=m Sets the initial submapping to m, provided that it is compatible with current codepage /NOHI Forbids KEYB to load any data to upper memory /B Forbids KEYB to produce sound alerts (beep) /S Safemode: open compilations loading, strings, some critical commands are forbidden /U Unloads a KEYB previously loaded in memory /? Shows the fast help 1.2.- Exit codes and causes of errors FD-KEYB is compatible with the exit codes of MS-KEYB. However, as a large number of possible error causes is considered, an alternative numeration of errors is shown on screen at load time. ExitCode KEYB error code Error description ============================================================================== 0 0 Successful execution INVALID LANGUAGE, CODE PAGE OR INCORRECT SYNTAX 1 3 Missing keyboard identifier 1 11 Invalid modifier or switch 1 14 Specified file does not contain information for this layout/id 1 21 Required submapping does not match with current codepage: you are using /L=m but the requested submapping does not correspond with current CP BAD OR MISSING KEYBOARD DEFINITION FILE 2 4 Specified file could not be opened 2 13 Invalid file, or file corrupt 2 19 Incompatible version of keyboard descriptor (the compilation file or KL file are of an incompatible version) 2 20 Invalid checksum for data block: the compilation file is corrupt 3 10 The keyboard table could not be created 4 16 Error in communication with the CON device 5 17 The codepage has not been prepared 6 12 Codepage not found in keyboard definition file - INCOMPATIBLE KEYB OR VERSION FOUND 7 1 Different version of KEYB installed 7 2 Incompatible keyboard driver installed 7 18 Incompatible version of DR-KEYB installed --- Not present in MS-KEYB RESIDENT PART OF KEYB COULD NOT BE REMOVED 8 5 The resident part of KEYB could not be removed 8 8 KEYB was NOT installed UNEXPECTED PROBLEM: VISIT THE KEYB SITE FOR A NEWER VERSION OR CONTACT THE AUTHOR 9 6 Internal failure: Global memory space too small 9 7 KEYB (still) requires an AT/286 or better 9 9 Overloading is (still) not supported 9 15 KL file too large ((still) 3KB maximum) ============================================================================== 1.3.- FD-KEYB features The following is a brief list of features of FD-KEYB: * Programmability. The driver can be programmed using KL files. You can create customized KL files with the compiler, or use precompiled KL files, and use compilation packs of KL files, such as KEYBOARD.SYS. * MS-KEYB compatibility. FD-KEYB is compatible with MS-KEYB in commandline, DOS Multiplexer API and Exitcodes. Note however that Microsoft's KEYBOARD.SYS is not compatible with FD-KEYB. * Small size. Compared to MS-KEYB or xkeyb (around 6KB in resident size), FD-KEYB has a typical resident size of over 2KBs. This reduction is size is obtained by reubicating data and shrinking the memory used, and also by recycling BIOS keyboard support as much as possible. * Codepage support. FD-KEYB implements full codepage support. Unlike MS-KEYB, that supports 2 codepages per layout, the number of supported codepages in FD-KEYB is virtually limitless. The next chapter is extensively devoted to the codepage management of KEYB. * Extensive number of commands and effects: string output (including special chars and key combination simulation), diacritics, interrupt triggering (incl. Break, Print Screen, SysReq, etc.), managing system power and self configuring. The anexe document lists the supported commands. * Keys, key combinations, key pressing/releasing and E0-prefixed keys are supported and can be reprogrammed. * Automatic detection of keyboard type (that can be overriden with the /E and /9 switches) * Additional shifting and locking keys can be defined to create entire new planes of effects. * It can be automatically disabled/enabled by pressing Ctrl+Alt+F1/F2, respectively. The decimal separator char can be easily reprogrammed through the commandline or in KL files * It supports APL software by IBM * It implements specific software hooks for Japanese language. * Last but not least, it is open source software under the GNU-GPL 2.0, which is written mostly in x86 assembler (TASM), with a non-resident stub in Pascal (Turbo Pascal) 1.4.- Compiling the driver In order to compile the driver, you need a Turbo Pascal compiler that supports embedded TASM procedures, such as Borland/Turbo Pascal 7.0 (French version freely available under the Borland France site). The program is finally packed using the open source UPX/UCL packer. Respect to the structure of the program, just a couple of notes: - The program has a resident part in assembler, and a non-resident part in Pascal. - The resident part has two parts, a first core part that is always kept, corresponding with the basic int15h management (main code hooks at int15h, AH=4Fh), the multiplexer and other basic stuff. The second part is a collection of modules, that are discarded if not used. - Interrupts 15h and 2Fh are always hooked. Interrupt 9h is hooked when modules 6 onwards are loaded. Interrupt 16h is hooked if strings are used. - When strings are used, a secondary buffer is created. This buffer contains references to strings that are expanded into the primary buffer. This code is made by the int16h handler, that works otherwise transparently - When KEYB has to check wether a scancode/plane pressed is found, three tables are checked. The one for the particular submapping, then the one for the general submapping, and finally a third table catching Ctrl+Alt+F1/F2 and the numeric Del key. If it is not catched, then it is surrended back to BIOS. 2.- Codepage support ==================== Codepage support is an interesting topic requiring a full chapter. Each layout can be adapted to work with a certain number of codepages. Notice that the keyboard is part of the CON (console) device, thus KEYB will enforce consistency of codepages with DISPLAY.SYS and with the system as much as possible. 2.1.- The boot-up check When KEYB is loaded, the following sequence is followed in order to determine the codepage to be used. (1) Codepage specified by the user in the commandline. This overrides any other specification. (2) Codepage shown by DISPLAY.SYS, if any. If the user didn't specify a codepage, KEYB will check wether DISPLAY.SYS is present, and wether it has an active codepage. If both conditions are met (DISPLAY.SYS present and with active codepage), that codepage will be used by KEYB. (3) If DISPLAY.SYS is not present, or it doesn't have an active codepage, then KEYB will finally try the system codepage, obtained from interrupt AX=6601h of DOS in BX (this can be read running "CHCP" parameterless). Whenever FD-KEYB has determined the codepage that is to be used, it will read and search for it in the KL file to be loaded. If it is not found there, then KEYB will refuse to load. Otherwise, the first particular submapping implementing that codepage (or with cp 0) will be used. 2.2.- Interfacing with DISPLAY.SYS DISPLAY.SYS and KEYB form a functional unit that implements a codepage aware console. However, KEYB will never talk to DISPLAY after boot time (where KEYB asks DISPLAY the current codepage). KEYB will expect that DISPLAY requests it to change the codepage as appropriate (through the MuX interrupt already implemented). DISPLAY.SYS issues codepage change calls whenever it (the CONsole) is forced to change its codepage (by NLSFUNC or MODE CON CP SEL). FD-KEYB responds as appropriate to any call issued by DISPLAY.SYS to change the codepage. =============