ring3k.org


Ring3k FAQ

What is it?

ring3k is a user mode kernel that aims to implement the system call interface that Windows 2000 presents to user mode code, enabling Windows applications to run on top of Linux in their native environment without the performance hit of full an emulator such as QEMU.

It was inspired by User Mode Linux, and has some similarities to Wine and QEMU.

ring3k seeks a tradeoff between performance and implementation effort that is between that of QEMU and that of Wine, as shown by the following table:

Project Performance Implementation size
Wine Good (instructions executed natively) Huge - reimplement all Windows Dlls 15 years to version 1.0, and not complete
QEMU OK (instructions translated before execution) Small (Implementation of virtual hardware)
Ring3k Good (instructions executed natively), system calls through ptrace Implement new virtual kernel and virtual drivers only

What does it do?

ring3k enables Windows programs to run on top of Linux by starting a full Windows system, from the boot process.

smss.exe is the first user mode process started by the kernel during windows bootup. The structure of Windows user processes can be seen using process explorer as shown below.

Windows XP process tree

The processes are as follows:

smss.exeSession Management SubSystem.
csrss.exeClient Server Runtime SubSystem.
lsass.exeLocal Security Authority SubSystem.
winlogon.exeWinstation logon process
svchost.exeService DLL wrapper
explorer.exeThe desktop process

In ring3k, minitris.exe is now started in place of winlogon.exe while work is in progress to get other parts of the startup working.

How does it work?

Both UML and ring3k work by (ab)using the Linux ptrace interface to trap system calls and exceptions generated by ring 3 code. User mode kernels act as a debugger, examining the exceptions and system calls that are made by Windows code running in another process, and responding to them as an NT kernel would.

User mode kernel structure

Which license is the code under?

ring3k code is distributed under the LGPL.

What are the requirements?

To run a Windows environment on top of this kernel, you'll need:

How do you build and run it?

tar zxvf ~/ring3k-0.0.23.tar.gz
cd ring3k-0.0.23
./configure
make
ln -s ~/name_of_your_windows.iso win2k.iso
make test
./ring3k -t >& x

This should generate a log named x which can be used for debugging.

For Windows XP, use the following ln command:

ln -s ~/name_of_your_windows.iso winxp.iso

What does the output look like?

Here is the typical test output, logging when running Windows 2000 smss.exe and Windows XP smss.exe.

What can I do to help out?

Any of the following are helpful:

If you're interested in helping out on this project and don't know where to start, mail mikem@ring3k.org.

Is Windows XP supported?

Yes, but support is not yet as extensive as for Windows 2000 system calls.

What is implemented, and what is not?

The basics of scheduling, synchronization, timers memory management, IPC (ports+pipes), filesystem access and the registry are work.

In the UI layer, simple graphics and some window messages work.

Summary from 'make stat' for ring3k-0.0.22:

ntsyscall:
        undeclared:     57 (19%)
        declared:       54 (18%)
        implemented:   183 (62%)
        total:         294

uisyscall:
        undeclared:    564 (84%)
        declared:        0 ( 0%)
        implemented:   106 (16%)
        total:         670

Total LOC:     26516

How is code developed and validated?

ring3k code is developed and validated using Black box testing. The behaviour of Windows XP/2000 is determined using by writing a conformance test. Ring3k is then written to match the observed behaviour.

See How Samba was written and the Wine developer's guide's chapter on Writing Conformance tests for information on how black box tests are written.

The GNU coding standards also offer some advice.

ring3k's tests are written as native executables, in order to minimize runtime dependencies.

What about other Windows compatibility projects?

The ring3k developers are aware of other Windows compatibility projects. The ring3k projects goals, methodologies and licensing do not overlap with those of any other Windows kernel project, so no code from existing kernel projects will be used.

The ring3k project does not intend to replicate the source code, style or inner workings of the NT kernel.

Code will only be drawn from the Wine project (which is also LGPL), if it is needed.

What is a Native executable?

An NT Native executable is one that has IMAGE_OPTIONAL_HEADER.Subsystem = IMAGE_SUBSYSTEM_NATIVE (1) in its PE header. Native executables do not depend on the Win32 subsystem, and primarily use the NT native API (NT system call interface) defined in ntdll.dll.

ring3k is written to run Windows Native executables.

How do you build a native executable on Linux?

Windows Native executables, which use the NT native API can be built on Linux using mingw32. Create a native.c that looks something like this:

#include <windef.h>
#include <winnt.h>
#include <ntdll.h>
#include <ntdef.h>

#define NtCurrentProcess() ((HANDLE)-1)

NTSTATUS NTAPI NtTerminateProcess(HANDLE,NTSTATUS);
void NtProcessStartup()
{
    /* do something */
    NtTerminateProcess( NtCurrentProcess(), 0 );
}

To build native.exe from native.c, the Makefile will look like this:

CC=i586-mingw32msvc-cc
LDFLAGS=-nostartfiles -nodefaultlibs -Wl,--subsystem=native

native.exe: native.c
        $(CC) -Wall -o  lt; -lntdll $(LDFLAGS) -e _NtProcessStartup

How do you run a native executable on Windows?

One way to run a native process is to use the BootExecute key. Native programs listed in the BootExecute key are run at startup and debug output is dumped to the start screen.

ring3k includes HostNT.exe which can be used to invoke an NT native application from the windows command prompt and monitor its debug output.

As a native program has no associated console, getting output from it isn't straight forward. HostNT solves this problem by providing a mailslot for the native application to send console output messages to.

When running the native.exe generated above in HostNT, you'll see something like:

C:\hostnt>hostnt native.exe
process exited (00000000)

C:\hostnt>

This is a useful tool for writing short programs that check the behaviour of the NT Native API and is used as the basis for ring3k's test suite.

Where can I learn more about the NT Native API?

The Windows NT/2000 Native API Reference is a good source of information about the Native API.

Feng Yuan's Windows Graphics Programming is a good start on the windows graphics architecture.

Metasploit has a table of Windows sytem calls for various versions of Windows.



© Copyright 2008-2009 Mike McCormack