Howto: Implementation of new system service calls (I)

By Michael Schöbel

The kernel interface to user mode applications can be described by the set of system service calls. Implementing a new service call is the easiest way to expose new kernel functions to user mode programs.

This post describes the necessary steps to implement a new system service call in the WRK.

First, some background information about system service calls and system service dispatching in Windows is given. Afterwards, the user mode side of directly calling system services is described. Finally, the kernel mode side is examined and a detailed description of how new service calls can be implemented is given.

System service dispatching

A special, processor dependent, instruction is called to trigger a system service call. On 32bit x86 processors Windows used the int 0x23h, the sysenter (Intel CPUs) or the syscall (AMD CPUs) instruction. The service number and possible arguments are stored depending on which of these ways the system service is called. The system service dispatcher delegates the call to an appropriate function depending on the system service number. This delegation is done by looking into a system service dispatch table with mappings from service number to system function. After copying the arguments from the caller's user mode to its kernel mode stack, the system service function is executed.

From the user mode point of view the kernel interface is wrapped in the Windows API, therefore in most cases no explicit system service call must be made by application developers. User mode applications for example call functions from NTDLL.DLL and the corresponding implementation deals with the kernel invocation.

Extending operating system functionality

The introduction of new operating system functionality to the kernel can be achieved in different ways:

Device drivers can be loaded into the kernel and then manipulate the system service table or they can be called in a driver-specific way. Without the kernel source code, this is the only way to extend the Windows kernel functionality

Extending existing service calls Many of the system service call interfaces are designed in a flexible way. For example NtSetInformationThread (see /base/ntos/ps/psquery.c) is used for almost all thread-related operations. An argument of the type THREADINFOCLASS (enumeration) determines the operation to be executed. Such a function can be easily extended by introducing new elements into the enumeration.

Creating new system service calls is the appropriate way to expose new kernel functionality if no matching system service already exists. This method requires the introduction of a new system service number and the modification of the system service dispatch table.

In this post we will concentrate on the last possibility: How can a new system service call be implemented? The next section provides the information needed for user mode side development for extended kernels. The section afterwards examines the kernel mode side.

System service calls - user mode side

From the (user mode) application development point of view the following questions have to be answered: How is a system service call invoked programmatically? How are arguments passed to the service routine?

NTSTATUS QuerySystemTime(OUT PLARGE_INTEGER CurrentTime) {

        void** stackFrame = &CurrentTime;

        // call NtQuerySystemTime

        __asm {
//            mov eax, 0x00AE         // XP
                mov eax, 0x00B6               // EE
                mov edx, stackFrame
                int 0x2E
        }
}

• the signature of the system service function for stackFrame initialization
• the system service call number in the system service dispatch table

With this information, a generic wrapper function can be implemented and the new system service function can be used in user mode applications. To hide the low-level details from application developers, a user mode DLL can be designed to wrap the system service call.

System service calls - kernel mode side

The mechanism of system service call dispatching is the same for all service calls. Therefore, only the system service call dispatch table must be modified to hold a reference to the newly created service and the service function must be implemented.

..
TABLE_ENTRY  QueryPortInformationProcess, 0, 0
TABLE_ENTRY  GetCurrentProcessorNumber, 0, 0
TABLE_ENTRY  WaitForMultipleObjects32, 1, 5
TABLE_ENTRY  MyNewSystemServiceCall, 1, 1

TABLE_END 296
..

..
SYSSTUBS_ENTRY8  295, WaitForMultipleObjects32, 5
SYSSTUBS_ENTRY1  296, MyNewSystemServiceCall, 1
SYSSTUBS_ENTRY2  296, MyNewSystemServiceCall, 1
SYSSTUBS_ENTRY3  296, MyNewSystemServiceCall, 1
SYSSTUBS_ENTRY4  296, MyNewSystemServiceCall, 1
SYSSTUBS_ENTRY5  296, MyNewSystemServiceCall, 1
SYSSTUBS_ENTRY6  296, MyNewSystemServiceCall, 1
SYSSTUBS_ENTRY7  296, MyNewSystemServiceCall, 1
SYSSTUBS_ENTRY8  296, MyNewSystemServiceCall, 1

STUBS_END

Summary

The implementation of a new system service call with the Windows Research Kernel requires only a few steps:

• Insert entries for the new system service call into the system service dispatch table (files systable.asm and sysstubs.asm).
• Implement the new system service function.
• Create a user mode wrapper function for the system service call.

The second part of this post introduces a simple example application. Additionally the whole "HOWTO" and a WRK patch for the example will be provided for download.

Comments