WRK System Service Calls Made Simple

By Alexander Schmidt

Michael created an exhaustive tutorial on how to create a new system service call in the Windows Research Kernel in his HowTo series. An important part is to define the system service dispatch table that contains the new system call, otherwise no user mode application could use it. Creating this dispatch table requires modifying two assembly language files, sysstubs.asm and systable.asm, which in our opinion has proven error prone and tedious.

Therefore, we created a tool that generates the system service table automatically when the WRK is built. It is available as binary for x86 platforms and as sources. It can be downloaded from wrktools.codeplex.com.

Let's assume, you want to create a new system call, say MyNewSystemCall, with the following signature for the x86 platform:

NTSTATUS MyNewSystemCall(
        ULONG FirstParameter,
        PVOID SecondParameter);

When it comes to create the system service dispatch table, you usually ended up editing the sysstubs.asm and systable.asm files. Apparently, we thought, Microsoft does not create these files manually, they might rather generate it somehow. It is also important that the counter part of the system service dispatch table, the ntdll.dll library, has the exact same structure, otherwise the behavior of any system service might be undefined.

We examined the base\ntos\ke\i386 directory a little bit closer and found the following files:

• services.tab
• services.stb, and
• table.stb

It turns out that service.tab file contains the complete list of system services shipped with the WRK, exactly in the same order as they appear in the systable.asm file. The table.stb file provides the header of the systable.asm file, while the services.stb file provides the header for the sysstubs.asm file.

So, we came up with our tool that combines all three files and generates the necessary assembly files. All you have to do, when using our generator, is to append your new system call to the end - keep in mind that the order is very important - of the services.tab file. The syntax is pretty simple:

1. A semi-colon (;) starts a comment until the end of the line
2. Each line - if not a comment - defines a new system call.
3. The syntax for a system call is: <Name>,<Number of Argument>. Where Name is the function name of your system call without the prefix Nt (this is added by a macro) and Number of Arguments is, well, the number of arguments your system call has.

So consider the following excerpt of the services.tab as is shipped with the WRK:

; ...
OpenKeyedEvent,3
ReleaseKeyedEvent,4
WaitForKeyedEvent,4
QueryPortInformationProcess,0
GetCurrentProcessorNumber,0
WaitForMultipleObjects32,5

After you added your system service, the file should look like this:

; ...
OpenKeyedEvent,3
ReleaseKeyedEvent,4
WaitForKeyedEvent,4
QueryPortInformationProcess,0
GetCurrentProcessorNumber,0
WaitForMultipleObjects32,5
; New system calls go below here :)
MyNewSystemCall,2

That's pretty much it.

In order to incorporate our tool into the build process of the WRK, please perform the following steps:

1. Copy the mksystbl.exe file to the tools\x86 directory of the WRK.
2. Make sure, you have the VS 2008 runtime environment installed. You have it definitely, if you have Visual Studio 2008 installed. Otherwise download and install it before using our generator. (You may also build the tool on your own from the sources.)
3. Copy the provided makefile to the base\ntos directory of the WRK.

The makefile simply adds a new rule to the original makefile:

$(systable): $(services)
        @echo Generating system services table ...
        @cd $(MAKEDIR)\ke\$(targ)
                mksystbl.exe /machine:$(lmachine)
        @cd $(MAKEDIR)

Which means that whenever you modify the services.tab file ($(services)), the tool will generate both the sysstubs.asm and the systable.asm files before the compilation/linking of the rest of the kernel starts.

For further details on how the tool exactly works, you may have a look at the sources of the tool, too. Please give it a try at wrktools.codeplex.com and let us know your feedback.

Comments