/****************************************************************//*                                                              *//*                            NLS.H                             *//*                           FreeDOS                            *//*                                                              *//*    National Language Support data structures                 *//*                                                              *//*                   Copyright (c) 2000                         *//*                         Steffen Kaiser                       *//*                      All Rights Reserved                     *//*                                                              *//* This file is part of FreeDOS.                                *//*                                                              *//* DOS-C 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, or (at your option) any later version.                    *//*                                                              *//* DOS-C 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 DOS-C; see the file COPYING.  If not,     *//* write to the Free Software Foundation, 675 Mass Ave,         *//* Cambridge, MA 02139, USA.                                    *//****************************************************************//* one byte alignment */#include <algnbyte.h>/* *	Description of the organization of NLS information -- 2000/02/13 ska * *	Glossar: *	NLS package -- NLS information incl. any code required to access or *		correctly interprete this particular information * *	Abbreviation: *	(NLS) pkg -- NLS package * *	The code included into the kernel does "only" support NLS packages *	structurally compatible with the one of the U.S.A. / CP437. *	I guess that most NLS packages has been tweaked to be compatible, *	so that this is not a real limitation, but for all other packages *	the external NLSFUNC can supply every piece of code necessary. *	To allow this the interface between the kernel and NLSFUNC has been *	extended; at the same time the interface has been reduced, because some *	of the API functions do not seem to offer any functionality required *	for now. This, however, may be a misinterpretation because of *	lack of understanding. * *	The supported structure consists of the following assumptions: *	1) The pkg must contain the tables 2 (Upcase character), 4 *		(Upcase filename character) and 5 (filename termination *		characters); because they are used internally. *	2) The tables 2 and 4 must contain exactly 128 (0x80) characters. *		The character at index 0 corresponses to character 128 (0x80). *		The characters in the range of 0..0x7f are constructed out of *		the 7-bit US-ASCII (+ control characters) character set and are *		upcased not through the table, but by the expression: *			(ch >= 'a' && ch <= 'z')? ch - 'a' + 'A': ch *			with: 'a' == 97; 'z' == 122; 'A' == 65 *	3) The data to be returned by DOS-65 is enlisted in the *		nlsPointer[] array of the nlsPackage structure, including *		the DOS-65-01 data, which always must be last entry of the *		array. *	4) DOS-38 returns the 34 bytes beginning with the byte at offset *		4 behind the size field of DOS-65-01. * *	It seems that pure DOS can internally maintain two NLS pkgs: *	NLS#1: The hardcoded pkg of U.S.A. on CP437, and *	NLS#2: the pkg loaded via COUNTRY= from within CONFIG.SYS. *	I do interprete this behaviour as follows: *	CONFIG.SYS is read in more passes; before COUTRY= can be evaluated, *	many actions must be performed, e.g. to load kernel at all, open *	CONFIG.SYS and begin reading. The kernel requires at least two *	NLS information _before_ COUNTRY= has been evaluated - both upcase *	tables. To not implement the same function multiple times, e.g. *	to upcase with and without table, the kernel uses the default *	NLS pkg until a more appropriate one can be loaded and hopes that *	the BIOS (and the user) can live with its outcome. *	Though, theoretically, the hardcoded NLS pkg could be purged *	or overwritten once the COUNTRY= statement has been evaluated. *	It would be possible that this NLS pkg internally performs different *	purposes, for now this behaviour will be kept. * *	The current implementation extends the above "two maintained *	NLS pkgs" into that the kernel chains all NLS pkgs loaded in *	memory into one single linked list. When the user does neither *	wants to load other NLS pkgs without executing NLSFUNC and the *	loaded NLS pkgs do not contain code themselves, no other code is *	required, but some memory to store the NLS pkgs into. * *	Furthermore, because the kernel needs to include the code for the *	hardcoded NLS pkg anyway, every NLS pkg can use it; so only *	NLS pkgs that structurally differ from U.S.A./CP437 actually need *	to add any code and residently install the MUX handler for NLSFUNC. *	This technique reduces the overhead calling the MUX handler, when *	it is not needed. *	However, NLSFUNC is always required if the user wants to return *	information about NLS pkgs _not_ loaded into memory. * *=== Attention: Because the nlsInfoBlock structure differs from the *===	the "traditional" (aka MS) implementation, the MUX-14 interface *===	is _not_ MS-compatible, although all the registers etc. *===	do conform. -- 2000/02/26 ska * *	Previous failed attempts to implement NLS handling and a full- *	featured MUX-14 supporting any-structured NLS pkgs suggest *	to keep the implement as simple as possible and keep the *	optimization direction off balance and to tend toward either *	an optimization for speed or size. * *	The most problem is that the MUX interrupt chain is considered *	highly overcrowded, so if the kernels invokes it itself, the *	performance might decrease dramatically; on the other side, the *	more complex the interface between kernel and a _probably_ installed *	external NLSFUNC becomes the more difficult all the stuff is becoming *	and, most importantly, the size grows unnecessarily, because many *	people don't use NLSFUNC at all. * *	The kernel uses the NLS pkg itself for two operations: *	1) DOS-65-2x and DOS-65-Ax: Upcase character, string, memory area, & *	2) whenever a filename is passed into the kernel, its components *		must be identified, invalid characters must be detected *		and, finally, all letters must be uppercased. *	I do not consider operation 1) an action critical for performance, *	because traditional DOS programming praxis says: Do it Yourself; so *	one can consider oneself lucky that a program aquires the upcase *	table once in its life time (I mean: lucky the program calls NLS at all). *	Operation 2), in opposite, might dramatically reduce performance, if *	it lacks proper implementations. * *	Straight forward implementation: *	The basic implementation of the NLS channels all requests of DOS-65, *	DOS-66, and DOS-38 through MUX-14. Hereby, any external program, such *	as NLSFUNC, may (or may not) install a piece of code to filter *	one, few, or all requests in order to perform them itself, by default *	all requests will end within the root of the MUX interrupt, which is *	located within the kernel itself. An access path could look like this: *	1. Call to DOS-65-XX, DOS-66-XX, or DOS-38. *	2. The kernel is enterred through the usual INT-21 API handler. *	3. The request is decoded and one of the NLS.C function is called. *	4. This function packs a new request and calls MUX-14. *	5. Every TSR/driver hooking INT-2F will check, if the request is *		directed for itself; *	5.1. If not, the request is passed on to the next item of the MUX *		interrupt chain; *	5.2. If so, the TSR, e.g. NLSFUNC, tests if the request is to be *		performed internally; *	5.2.1. If so, the request is performed and the MUX-14 call is *		terminated (goto step 8.) *	5.2.2. If not, the request is passed on (see step 5.1.) *	6. If all TSRs had their chance to filter requests, but none decided *		to perform the request itself, the kernel is (re-)enterred *		through its INT-2F (MUX) API handler. *	7. Here the request is decoded again and performed with the kernel- *		internal code; then the MUX-14 call is terminated. *	8. When the MUX-14 call returns, it has setup all return parameters *		already, so the INT-21 call is terminated as well. * *	Note: The traditional MUX-14 is NOT supported to offer functionality *	to the kernel at the first place, but to let the kernel access and *	return any values they must be loaded into memory, but the user may *	request information through the DOS-65 interface of NLS pkgs _not_ *	already loaded. Theoretically, NLSFUNC needs not allocate any internal *	buffer to load the data into, because the user already supplied one; *	also if the kernel would instruct NLSFUNC to load the requested *	NLS pkg, more memory than necessary would be allocated. However, all *	except subfunction 1 return a _pointer_ to the data rather than the *	data itself; that means that NLSFUNC must cache the requested data *	somewhere, but how long? * *	Performance tweaks: *	When the system -- This word applies to the combination of kernel and *	any loaded MUX-14 extension