8.8. KERNEL32 Module

8.8.1.1. NT implementation

Windows implements console solely in the Win32 subsystem. Under NT, the real implementation uses a dedicated subsystem csrss.exe Client/Server Run-time SubSystem) which is in charge, amont other things, of animating the consoles. Animating includes for example handling several processes on the same console (write operations must be atomic, but also a character keyed on the console must be read by a single process), or sending some information back to the processes (changing the size or attributes of the console, closing the console). Windows NT uses a dedicated (RPC based) protocol between each process being attached to a console and the csrss.exe subsystem, which is in charge of the UI of every console in the system.

8.8.1.2. Wine implementation

Wine tries to integrate as much as possible into the Unix consoles, but the overall situation isn't perfect yet. Basically, Wine implements three kinds of consoles:

• the first one is a direct mapping of the Unix console into the Windows environment. From the windows program point of view, it won't run in a Windows console, but it will see its standard input and output streams redirected to files; thoses files are hooked into the Unix console's output and input streams respectively. This is handy for running programs from a Unix command line (and use the result of the program as it was a Unix programs), but it lacks all the semantics of the Windows consoles.

• the second and third ones are closer to the NT scheme, albeit different from what NT does. The wineserver plays the role of the csrss.exe subsystem (all requests are sent to it), and are then dispatched to a dedicated wine process, called (surprise!) wineconsole which manages the UI of the console. There is a running instance of wineconsole for every console in the system. Two flavors of this scheme are actually implemented: they vary on the backend for the wineconsole. The first one, dubbed user, creates a real GUI window (hence the USER name) and renders the console in this window. The second one uses the (n)curses library to take full control of an existing Unix console; of course, interaction with other Unix programs will not be as smooth as the first solution.

The following table describes the main implementation differences between the three approaches.

The Win32 objects behind a console can be created in several occasions:

• When the program is started from wineconsole, a new console object is created and will be used (inherited) by the process launched from wineconsole.

• When a program, which isn't attached to a console, calls AllocConsole(), Wine then launches wineconsole, and attaches the current program to this console. In this mode, the USER32 mode is always selected as Wine cannot tell the current state of the Unix console.

Please also note, that starting a child process with the CREATE_NEW_CONSOLE flag, will end-up calling AllocConsole() in the child process, hence creating a wineconsole with the USER32 backend.

Another interesting point to note is that Windows implements handles to console objects (input and screen buffers) only in the KERNEL32 DLL, and those are not sent nor seen from the NTDLL level, albeit, for example, console are waitable on input. How is this possible? Well, Windows NT is a bit tricky here. Regular handles have an interesting property: their integral value is always a multiple of four (they are likely to be offsets from the beginning of a table). Console handles, on the other hand, are not multiple of four, but have the two lower bit set (being a multiple of four means having the two lower bits reset). When KERNEL32 sees a handle with the two lower bits set, it then knows it's a console handle and takes appropriate decisions. For example, in the various kernel32!WaitFor*() functions, it transforms any console handle (input and output - strangely enough handles to console's screen buffers are waitable) into a dedicated wait event for the targetted console. There's an (undocumented) KERNEL32 function GetConsoleInputWaitHandle() which returns the handle to this event in case you need it. Another interesting handling of those console's handles is in ReadFile() (resp. WriteFile()), which behavior, for console's handles, is transferred to ReadConsole() (resp. WriteConsole()). Note that's always the ANSI version of ReadConsole() / WriteConsole() which is called, hence using the default console's code page. There are some other spots affected, but you can look in dlls/kernel to find them all. All of this is implemented in Wine.

Wine also implements the same layout of the registry for storing the preferences of the console as Windows does. Those settings can either be defined globally, or on a per process name basis. wineconsole provides the choice to the user to pick you which registry part (global, current running program) it wishes to modify the settings for.

8.8.2.1. Starting a NE (Win16) process

Wine is also able to run 16 bit processes, but this feature is only supported on Intel IA-32 architectures.

When Wine is requested to run a NE (Win 16 process), it will in fact hand over the execution of it to a specific executable winevdm. VDM stands for Virtual DOS Machine. This winevdm is a Winelib application, but will in fact set up the correct 16 bit environment to run the executable. We will get back later on in details to what this means.

Any new 16 bit process created by this executable (or its children) will run into the same winevdm instance. Among one instance, several functionalities will be provided to those 16 bit processes, including the cooperative multitasking, sharing the same address space, managing the selectors for the 16 bit segments needed for code, data and stack.

Note that several winevdm instances can run in the same Wine session, but the functionalities described above are only shared among a given instance, not among all the instances. winevdm is built as Winelib application, and hence has access to any facility a 32 bit application has.

Each Win16 application is implemented in winevdm as a Win32 thread. winevdm then implements its own scheduling facilities (in fact, the code for this feature is in the krnl386.exe DLL). Since the required Win16 scheduling is non pre-emptive, this doesn't require any underlying OS kernel support.

8.8.2.2. SysLevels

SysLevels are an undocumented Windows-internal thread-safety system dedicated to 16 bit applications (or 32 bit applications that call - directly or indirectly - 16 bit code). They are basically critical sections which must be taken in a particular order. The mechanism is generic but there are always three syslevels:

• level 1 is the Win16 mutex,

• level 2 is the USER mutex,

• level 3 is the GDI mutex.

When entering a syslevel, the code (in dlls/kernel/syslevel.c) will check that a higher syslevel is not already held and produce an error if so. This is because it's not legal to enter level 2 while holding level 3 - first, you must leave level 3.

Throughout the code you may see calls to _ConfirmSysLevel() and _CheckNotSysLevel(). These functions are essentially assertions about the syslevel states and can be used to check that the rules have not been accidentally violated. In particular, _CheckNotSysLevel() will break probably into the debugger) if the check fails. If this happens the solution is to get a backtrace and find out, by reading the source of the wine functions called along the way, how Wine got into the invalid state.

8.8.2.3. Memory management

Every Win16 address is expressed in the form of selector:offset. The selector is an entry in the LDT, but a 16 bit entry, limiting each offset to 64 KB. Hence, the maximum available memory to a Win16 process is 512 MB. Note, that the processor runs in protected mode, but using 16 bit selectors.

Windows, for a 16 bit process, defines a few selectors to access the "real" memory (the one provided) by DOS. Basically, Wine also provides this area of memory.