{"componentChunkName":"component---src-templates-post-template-js","path":"/windows-windriver-002-irp-en","result":{"data":{"markdownRemark":{"id":"f1feb68f-e978-537f-b230-146fd4cb3fbc","html":"
\n

This page has been machine-translated from the original page.

\n
\n

I hit a wall when trying Windows kernel debugging: there are very few kernel drivers whose detailed specifications are publicly available.

\n

So I decided that if none existed, I would just build one myself, and started developing a kernel driver.

\n

When working on kernel driver development, I am basically proceeding with the following book as a reference.

\n

Reference: Windows Kernel Driver Programming

\n

I summarized how to configure kernel debugging in the following article.

\n

Reference: First steps for kernel debugging a Windows 10 environment with WinDbg

\n

In the previous article, I set up DebugView, created a driver that only outputs the OS version with KdPrint, and performed live debugging.

\n

This time I want to create a driver with a bit more behavior and debug it.

\n\n

Table of Contents

\n\n

Kernel programming

\n

I am developing this kernel driver based on Windows Kernel Driver Programming.

\n

The WDK (Windows Driver Kit) that I installed last time contains the libraries and header files used for kernel driver development.

\n

Kernel APIs are composed of C-language functions, but they differ from user-mode development mainly in the following ways.

\n

How kernel driver development differs from user mode

\n

Below is a quotation from Windows Kernel Driver Programming about how kernel driver development differs from user mode development.

\n\n

Structured Exception Handling (SEH)

\n

SEH is a feature for appropriately handling situations with specific exception codes, such as hardware failures.

\n

By using SEH, you can write programs that properly release resources such as memory blocks and files even when an exception occurs.

\n

SEH provides two mechanisms: an “exception handler” and a “termination handler”.

\n

Exception handlers are used to deal with specific errors.

\n

Reference: Writing an Exception Handler | Microsoft Docs

\n

Meanwhile, a termination handler can be made to run regardless of whether a code block finishes normally or an exception occurs.

\n

Reference: Writing a Termination Handler | Microsoft Docs

\n

When developing kernel drivers, you need to use SEH and implement exception handling with one of the mechanisms above.

\n

Reference: Structured Exception Handling (C/C++) | Microsoft Docs

\n

Kernel functions

\n

In kernel driver development, the C standard library is basically unavailable.

\n

Instead, kernel driver development uses functions exported from kernel components.

\n

Many kernel functions are implemented in Ntoskrnl.exe.

\n

Some of the functions implemented in Ntoskrnl.exe are documented, while others are not.

\n

Kernel function names follow certain conventions, and prefixes are attached according to purpose.

\n

The following Wikipedia page had a detailed explanation of the prefix mappings.

\n

Reference: ntoskrnl.exe - Wikipedia

\n

Documented kernel functions can be referenced on pages such as the following.

\n

Reference: Windows kernel - Windows drivers | Microsoft Docs

\n

Memory allocation in kernel drivers

\n

The kernel provides the following two memory pools that drivers can use.

\n\n

In addition, the nonpaged pool can separately control executable and non-executable regions.

\n

Using nonpaged pool that is not paged out guarantees that page faults will not occur, but it seems that when developing drivers, using paged pool as much as possible is recommended.

\n

Reference: ExAllocatePool function (wdm.h) - Windows drivers | Microsoft Docs

\n

Device objects

\n

As a rule, a kernel driver needs to create one or more device objects.

\n

A device object is what the OS uses to represent a device.

\n

Reference: Introduction to Device Objects - Windows drivers | Microsoft Docs

\n

A device object is created as an instance of the DEVICE_OBJECT structure.

\n

Kernel drivers communicate with client applications through device objects.

\n

Reference: DEVICEOBJECT (wdm.h) - Windows drivers | Microsoft Docs

\n

Creating a kernel driver and client application

\n

I will develop SecondDriverSample while transcribing the code explained in Chapter 4 of Windows Kernel Driver Programming.

\n

In Chapter 4, a set consisting of a kernel driver and a client application that controls thread priority is created.

\n

Scheduling priorities

\n

To be honest, I did not really know what setting thread priority with the Windows API meant, so I looked into it briefly.

\n

In Windows, threads are scheduled according to thread priority.

\n

Thread priority is determined by the following two conditions.

\n\n

The process priority class can be set to one of the following and can be configured with SetPriorityClass.

\n

By default, the process priority class seems to be THREAD_PRIORITY_NORMAL.

\n\n

On the other hand, one of the following thread priority levels is set within each priority class.

\n

It can be changed with SetThreadPriority.

\n

Here as well, THREAD_PRIORITY_NORMAL is assigned by default.

\n\n

Reference: SetPriorityClass function (processthreadsapi.h) - Win32 apps | Microsoft Docs

\n

Reference: SetThreadPriority function (processthreadsapi.h) - Win32 apps | Microsoft Docs

\n

Although each thread’s priority is determined by a combination of these settings, as shown in the table at the link below, it seems that not all priority levels can be flexibly set with the usual configuration methods.

\n

Reference: Scheduling Priorities - Win32 apps | Microsoft Docs

\n

Therefore, the goal of the driver and client developed in Chapter 4 is to make thread priority configurable more flexibly.

\n

Creating the DriverEntry function

\n

The base procedure is the same as the one I used in the earlier article.

\n

First, create the DriverEntry function, which will serve as the entry point.

\n

In the DriverEntry function, implement the following processing.

\n\n

As mentioned earlier, that is why the unload routine and device object are necessary.

\n

For details, the “Required Standard Driver Routines” section below is helpful.

\n

Reference: Introduction to Standard Driver Routines - Windows drivers | Microsoft Docs

\n

Dispatch routines are what process IRPs (incoming I/O request packets).

\n

IRPs store information about many different kinds of requests.

\n

To open the driver’s device handle, a kernel driver apparently needs to support at least the dispatch routines for IRP_MJ_CREATE and IRP_MJ_CLOSE.

\n

Reference: Dispatch Routine Functionality - Windows drivers | Microsoft Docs

\n

Reference: DRIVER_DISPATCH (wdm.h) - Windows drivers | Microsoft Docs

\n

Reference: DispatchCreate, DispatchClose, and DispatchCreateClose Routines - Windows drivers | Microsoft Docs

\n

A symbolic link to the device object is created so that the client can reference the kernel driver’s device object.

\n

For example, functions such as CreateFile take the symbolic link to the device object as their first argument.

\n

Reading the DriverEntry function

\n

Now, the DriverEntry function that I actually created while transcribing the code looked like this.

\n
extern \"C\" NTSTATUS\nDriverEntry(_In_ PDRIVER_OBJECT DriverObject, _In_ PUNICODE_STRING RegistryPath) {\n\tUNREFERENCED_PARAMETER(RegistryPath);\n\n\tKdPrint((\"SecondDriver DriverEntry started\\n\"));\n\n\tDriverObject->DriverUnload = SecondDriverUnload;\n\n\tDriverObject->MajorFunction[IRP_MJ_CREATE] = SecondDriverCreateClose;\n\tDriverObject->MajorFunction[IRP_MJ_CLOSE] = SecondDriverCreateClose;\n\tDriverObject->MajorFunction[IRP_MJ_DEVICE_CONTROL] = SecondDriverDeviceControl;\n\n\tUNICODE_STRING devName = RTL_CONSTANT_STRING(L\"\\\\Device\\\\SecondDriver\");\n\n\t//RtlInitUnicodeString(&devName, L\"\\\\Device\\\\ThreadBoost\");\n\tPDEVICE_OBJECT DeviceObject;\n\tNTSTATUS status = IoCreateDevice(DriverObject, 0, &devName, FILE_DEVICE_UNKNOWN, 0, FALSE, &DeviceObject);\n\tif (!NT_SUCCESS(status)) {\n\t\tKdPrint((\"Failed to create device (0x%08X)\\n\", status));\n\t\treturn status;\n\t}\n\n\tUNICODE_STRING symLink = RTL_CONSTANT_STRING(L\"\\\\??\\\\SecondDriver\");\n\tstatus = IoCreateSymbolicLink(&symLink, &devName);\n\tif (!NT_SUCCESS(status)) {\n\t\tKdPrint((\"Failed to create symbolic link (0x%08X)\\n\", status));\n\t\tIoDeleteDevice(DeviceObject);\n\t\treturn status;\n\t}\n\n\tKdPrint((\"SecondDriverSecondDriver DriverEntry completed successfully\\n\"));\n\n\treturn STATUS_SUCCESS;\n}
\n

Supporting dispatch routines

\n

For the time being, the following three lines were what caught my attention.

\n

This is where the dispatch routines are set up.

\n
DriverObject->MajorFunction[IRP_MJ_CREATE] = SecondDriverCreateClose;\nDriverObject->MajorFunction[IRP_MJ_CLOSE] = SecondDriverCreateClose;\nDriverObject->MajorFunction[IRP_MJ_DEVICE_CONTROL] = SecondDriverDeviceControl;
\n

DriverObject is a semi-documented structure that represents the image of a loaded kernel-mode driver.

\n
typedef struct _DRIVER_OBJECT {\n  CSHORT             Type;\n  CSHORT             Size;\n  PDEVICE_OBJECT     DeviceObject;\n  ULONG              Flags;\n  PVOID              DriverStart;\n  ULONG              DriverSize;\n  PVOID              DriverSection;\n  PDRIVER_EXTENSION  DriverExtension;\n  UNICODE_STRING     DriverName;\n  PUNICODE_STRING    HardwareDatabase;\n  PFAST_IO_DISPATCH  FastIoDispatch;\n  PDRIVER_INITIALIZE DriverInit;\n  PDRIVER_STARTIO    DriverStartIo;\n  PDRIVER_UNLOAD     DriverUnload;\n  PDRIVER_DISPATCH   MajorFunction[IRP_MJ_MAXIMUM_FUNCTION + 1];\n} DRIVER_OBJECT, *PDRIVER_OBJECT;
\n

Reference: DRIVEROBJECT (wdm.h) - Windows drivers | Microsoft Docs

\n

What does “the image of a loaded kernel-mode driver” actually mean? My understanding is that it is an object allocated and initialized by the kernel before DriverEntry is called, so I figure it is an object the kernel kindly sets up for us. (I still could not quite figure it out even after looking it up…)

\n

Here, by registering dispatch routines in MajorFunction, which is a member of this driver object, you can specify the concrete functions supported by the driver.

\n

MajorFunction is managed as an array of function pointers, and indices prefixed with IRP_MJ_ are predefined.

\n

The reason you only need to add the dispatch routines you support is that when the MajorFunction array is initialized by the kernel, all elements are set to nt!IopInvalidDeviceRequest, which indicates IRPs not supported by the driver.

\n

For that reason, only the dispatch routines you support are updated.

\n

Reference: DriverObject and DriverEntry

\n

Strings used by kernel functions

\n

When using strings with kernel functions, a structure of type UNICODE_STRING is basically expected.

\n

Reference: UNICODESTRING (ntdef.h) - Win32 apps | Microsoft Docs

\n

In the following lines of source code, the RTL_CONSTANT_STRING macro converts the path string \\\\Device\\\\SecondDriver into a UNICODE_STRING and stores it in the variable devName.

\n

The later symLink line works the same way.

\n
UNICODE_STRING devName = RTL_CONSTANT_STRING(L\"\\\\Device\\\\SecondDriver\");\n\nUNICODE_STRING symLink = RTL_CONSTANT_STRING(L\"\\\\??\\\\SecondDriver\");
\n

Reference: RtlInitString function (wdm.h) - Windows drivers | Microsoft Docs

\n

Creating a device object

\n

The required “creation of a device object” inside the DriverEntry function happens here.

\n

Although we already receive the kernel-initialized DriverObject as an argument to DriverEntry, it provides the information needed to create a device object with the IoCreateDevice function.

\n

If no device object exists, there is no way for a user-mode client to open a handle and communicate with the driver.

\n

A device object is created with the IoCreateDevice function.

\n

The IoCreateDevice function has the following form.

\n
NTSTATUS IoCreateDevice(\n  [in]           PDRIVER_OBJECT  DriverObject,\n  [in]           ULONG           DeviceExtensionSize,\n  [in, optional] PUNICODE_STRING DeviceName,\n  [in]           DEVICE_TYPE     DeviceType,\n  [in]           ULONG           DeviceCharacteristics,\n  [in]           BOOLEAN         Exclusive,\n  [out]          PDEVICE_OBJECT  *DeviceObject\n);
\n

Reference: IoCreateDevice function (wdm.h) - Windows drivers | Microsoft Docs

\n

The DriverObject of type PDRIVER_OBJECT received as the first argument is the one that was passed in as an argument to DriverEntry.

\n

The seventh argument receives a pointer to the newly created DeviceObject structure.

\n

Here, we pass a pointer to the newly declared DeviceObject of type PDEVICE_OBJECT.

\n

If the IoCreateDevice function runs successfully, the location referenced by this pointer is filled with a device object allocated from nonpaged pool.

\n

In addition, the third argument DeviceName lets you name the device object being created.

\n

Here, we set the devName defined earlier.

\n

For DeviceType, specify FILE_DEVICE_UNKNOWN.

\n

The documentation below summarizes other device types that can be set.

\n

Reference: Specifying Device Types - Windows drivers | Microsoft Docs

\n

The actual code looks like this.

\n
PDEVICE_OBJECT DeviceObject;\nNTSTATUS status = IoCreateDevice(DriverObject, 0, &devName, FILE_DEVICE_UNKNOWN, 0, FALSE, &DeviceObject);\nif (!NT_SUCCESS(status)) {\n\tKdPrint((\"Failed to create device (0x%08X)\\n\", status));\n\treturn status;\n}
\n

If the operation fails, an error message is output with the KdPrint function.

\n

Creating a symbolic link

\n

The device object has now been created, but user-mode clients still cannot access it as-is.

\n

To allow a user-mode client to access the device driver, you need to create a symbolic link to the device object.

\n

A symbolic link is created with the IoCreateSymbolicLink function.

\n

The function itself is simple: you just pass the symbolic link and the device object name, converted into PUNICODE_STRING structures, as arguments.

\n

Reference: IoCreateSymbolicLink function (wdm.h) - Windows drivers | Microsoft Docs

\n

The actual code looks like this.

\n
UNICODE_STRING symLink = RTL_CONSTANT_STRING(L\"\\\\??\\\\SecondDriver\");\nstatus = IoCreateSymbolicLink(&symLink, &devName);\nif (!NT_SUCCESS(status)) {\n\tKdPrint((\"Failed to create symbolic link (0x%08X)\\n\", status));\n\tIoDeleteDevice(DeviceObject);\n\treturn status;\n}
\n

If creating the symbolic link fails, all of the work done so far needs to be rolled back and the function should exit.

\n

Here, the IoDeleteDevice function is used to delete the device object from the system.

\n

Reference: IoDeleteDevice function (wdm.h) - Windows drivers | Microsoft Docs

\n

Once the device object and symbolic link have been created, the DriverEntry processing is complete.

\n

Setting up the routines assigned to the dispatch routines

\n

Next, let’s set up the routines that support CREATE and CLOSE, which were assigned in the following lines earlier.

\n
DriverObject->MajorFunction[IRP_MJ_CREATE] = SecondDriverCreateClose;\nDriverObject->MajorFunction[IRP_MJ_CLOSE] = SecondDriverCreateClose;
\n

In the program created in Chapter 4, both the CREATE and CLOSE routines are set to the same SecondDriverCreateClose.

\n

That is because its behavior is simply to accept IRP requests without doing any special processing.

\n

If you want to separate the processing for CREATE and CLOSE, you need to create and assign different routines.

\n

Let’s look at the actual code.

\n
_Use_decl_annotations_\nNTSTATUS SecondDriverCreateClose(PDEVICE_OBJECT DeviceObject, PIRP Irp) {\n\tUNREFERENCED_PARAMETER(DeviceObject);\n\n\tIrp->IoStatus.Status = STATUS_SUCCESS;\n\tIrp->IoStatus.Information = 0;\n\tIoCompleteRequest(Irp, IO_NO_INCREMENT);\n\treturn STATUS_SUCCESS;\n}
\n

Also, when I actually defined the dispatch routine exactly like the sample in the book, I got compiler error C2440 at build time.

\n
エラー\tC2440\t'=': 'NTSTATUS (__stdcall *)(PDRIVER_OBJECT,PIRP)' から 'PDRIVER_DISPATCH' に変換できません。
\n

I honestly did not understand it even after Googling, but when I tried defining the assigned function directly before the DriverEntry function instead of just declaring a prototype, it went away.

\n

I do not know whether that is really the right fix.

\n

Kernel development with WDM itself is no longer recommended, so maybe the latest compiler is tripping over something.

\n

Function annotations

\n

There is _Use_decl_annotations_ on the first line, but I had no idea what it was for.

\n

The documentation says that by using _Use_decl_annotations_, the annotations shown in the header within the scope of the same function are treated as if they also exist on the definition marked with _Use_decl_annotations_.

\n

Reference: c++ - what is Usedeclannotations meaning - Stack Overflow

\n

Reference: Annotating function behavior | Microsoft Docs

\n

I looked into it for a while, but I still could not understand its purpose, so I may add an update later if I figure it out.

\n

Receiving IRPs

\n

An IRP is a structure created by the I/O manager when an I/O request occurs from an application.

\n

IRPs are allocated from nonpaged pool and passed around as data packets.

\n

Let’s look at the code first.

\n

What the driver in Chapter 4 does is simple: after it rewrites some values in the IoStatus field of the IRP received as an argument, it passes the IRP to IoCompleteRequest.

\n
Irp->IoStatus.Status = STATUS_SUCCESS;\nIrp->IoStatus.Information = 0;\nIoCompleteRequest(Irp, IO_NO_INCREMENT);
\n

An IRP roughly consists of an IRP header and a stack location.

\n

After the I/O manager receives a request from an application, it allocates an IRP in nonpaged pool memory.

\n

It then initializes the IRP header and stack location and calls the driver’s dispatch routine.

\n

The following article was extremely helpful for understanding the detailed flow.

\n

Reference: Device driver course 25 | Science Park Co., Ltd.

\n

IoStatus is an I/O status block, and when the IRP completes, its completion state is set in IoStatus.Status.

\n

IoStatus.Information stores the number of bytes read or written.

\n

Since nothing is being read or written here, IoStatus.Information is set to 0.

\n

The IoCompleteRequest macro is used when a dispatch routine has completely finished processing an I/O request and returns the IRP to the I/O manager.

\n

This completes the definition of the dispatch routine that supports CREATE and CLOSE.

\n

Setting up device control

\n

Next, set up the device control routine configured by the line DriverObject->MajorFunction[IRP_MJ_DEVICE_CONTROL] = SecondDriverDeviceControl;.

\n

DEVICE_CONTROL is a general-purpose routine that can be used when exchanging data with a driver.

\n

DEVICE_CONTROL needs to receive three things: an input buffer, an output buffer, and a control code.

\n

Reference: IRPMJDEVICE_CONTROL - Windows drivers | Microsoft Docs

\n

Reference: Introduction to I/O Control Codes - Windows drivers | Microsoft Docs

\n

The control codes described in the following documentation are passed to DEVICE_CONTROL, and the operation is determined from them.

\n

Reference: DeviceIoControl function (ioapiset.h) - Win32 apps | Microsoft Docs

\n

Let’s look at the actual code.

\n
_Use_decl_annotations_\nNTSTATUS SecondDriverDeviceControl(PDEVICE_OBJECT, PIRP Irp) {\n\t// get our IO_STACK_LOCATION\n\tauto stack = IoGetCurrentIrpStackLocation(Irp);\n\tauto status = STATUS_SUCCESS;\n\n\tswitch (stack->Parameters.DeviceIoControl.IoControlCode) {\n\tcase IOCTL_SECOND_DRIVER_SET_PRIORITY:\n\t{\n\t\t// do the work\n\t\tif (stack->Parameters.DeviceIoControl.InputBufferLength < sizeof(ThreadData)) {\n\t\t\tstatus = STATUS_BUFFER_TOO_SMALL;\n\t\t\tbreak;\n\t\t}\n\n\t\tauto data = (ThreadData*)stack->Parameters.DeviceIoControl.Type3InputBuffer;\n\t\tif (data == nullptr) {\n\t\t\tstatus = STATUS_INVALID_PARAMETER;\n\t\t\tbreak;\n\t\t}\n\n\t\tif (data->Priority < 1 || data->Priority > 31) {\n\t\t\tstatus = STATUS_INVALID_PARAMETER;\n\t\t\tbreak;\n\t\t}\n\n\t\tPETHREAD Thread;\n\t\tstatus = PsLookupThreadByThreadId(ULongToHandle(data->ThreadId), &Thread);\n\t\tif (!NT_SUCCESS(status))\n\t\t\tbreak;\n\n\t\tKeSetPriorityThread((PKTHREAD)Thread, data->Priority);\n\t\tObDereferenceObject(Thread);\n\t\tKdPrint((\"Thread Priority change for %d to %d succeeded!\\n\",\n\t\t\tdata->ThreadId, data->Priority));\n\t\tbreak;\n\t}\n\n\tdefault:\n\t\tstatus = STATUS_INVALID_DEVICE_REQUEST;\n\t\tbreak;\n\t}\n\n\tIrp->IoStatus.Status = status;\n\tIrp->IoStatus.Information = 0;\n\tIoCompleteRequest(Irp, IO_NO_INCREMENT);\n\treturn status;\n}
\n

Obtaining the current stack location

\n

The IoGetCurrentIrpStackLocation function can obtain the current stack location.

\n
auto stack = IoGetCurrentIrpStackLocation(Irp);
\n

A stack location is defined by the IO_STACK_LOCATION structure.

\n

Drivers use the stack location inside an IRP to obtain driver-specific information related to the I/O operation.

\n

Reference: IoGetCurrentIrpStackLocation function (wdm.h) - Windows drivers | Microsoft Docs

\n

A stack location contains information such as the following.

\n\n

Reference: I/O Stack Locations - Windows drivers | Microsoft Docs

\n

Setting the requested priority on the thread

\n

This is the core implementation of the driver we are building this time.

\n

It is defined inside the SecondDriverDeviceControl function.

\n

The stack location obtained with the IoGetCurrentIrpStackLocation function contains information such as the passed control code.

\n

Because of that, processing branches based on the information in stack->Parameters.DeviceIoControl.IoControlCode.

\n

The source code is below.

\n
// switch (stack->Parameters.DeviceIoControl.IoControlCode)\ncase IOCTL_SECOND_DRIVER_SET_PRIORITY:\n{\n\t// do the work\n\tif (stack->Parameters.DeviceIoControl.InputBufferLength < sizeof(ThreadData)) {\n\t\tstatus = STATUS_BUFFER_TOO_SMALL;\n\t\tbreak;\n\t}\n\n\tauto data = (ThreadData*)stack->Parameters.DeviceIoControl.Type3InputBuffer;\n\tif (data == nullptr) {\n\t\tstatus = STATUS_INVALID_PARAMETER;\n\t\tbreak;\n\t}\n\n\tif (data->Priority < 1 || data->Priority > 31) {\n\t\tstatus = STATUS_INVALID_PARAMETER;\n\t\tbreak;\n\t}\n\n\tPETHREAD Thread;\n\tstatus = PsLookupThreadByThreadId(ULongToHandle(data->ThreadId), &Thread);\n\tif (!NT_SUCCESS(status))\n\t\tbreak;\n\n\tKeSetPriorityThread((PKTHREAD)Thread, data->Priority);\n\tObDereferenceObject(Thread);\n\tKdPrint((\"Thread Priority change for %d to %d succeeded!\\n\",\n\t\tdata->ThreadId, data->Priority));\n\tbreak;\n}
\n

IOCTL_SECOND_DRIVER_SET_PRIORITY is defined as follows.

\n
#define IOCTL_SECOND_DRIVER_SET_PRIORITY CTL_CODE(SECOND_DRIVER_DEVICE, 0x800, METHOD_NEITHER, FILE_ANY_ACCESS)
\n

The CTL_CODE macro generates a control code object from the information in its arguments.

\n

Reference: CTL_CODE macro (d4drvif.h) - Windows drivers | Microsoft Docs

\n

If the passed control code is IOCTL_SECOND_DRIVER_SET_PRIORITY, the processing is performed.

\n

The following code checks the input values.

\n
// do the work\nif (stack->Parameters.DeviceIoControl.InputBufferLength < sizeof(ThreadData)) {\n\tstatus = STATUS_BUFFER_TOO_SMALL;\n\tbreak;\n}\n\nauto data = (ThreadData*)stack->Parameters.DeviceIoControl.Type3InputBuffer;\nif (data == nullptr) {\n\tstatus = STATUS_INVALID_PARAMETER;\n\tbreak;\n}\n\nif (data->Priority < 1 || data->Priority > 31) {\n\tstatus = STATUS_INVALID_PARAMETER;\n\tbreak;\n}
\n

This time, because the goal is ultimately to set a thread’s priority, the passed buffer needs to store ThreadData.

\n

That is why the size of stack->Parameters.DeviceIoControl.InputBufferLength is checked.

\n

After checking the size, the buffer in the stack location is cast to ThreadData with (ThreadData*)stack->Parameters.DeviceIoControl.Type3InputBuffer.

\n

If it turns out to be a null pointer, an error is returned.

\n

Finally, it checks whether the Priority value in ThreadData falls within the prescribed range.

\n

Once validation of the passed data is complete, the thread priority is set with the KeSetPriorityThread function.

\n

The KeSetPriorityThread function needs to receive, as its first argument, a pointer to the thread whose priority is to be set.

\n

Reference: KeSetPriorityThread function (wdm.h) - Windows drivers | Microsoft Docs

\n

Therefore, the PsLookupThreadByThreadId function is used to obtain a pointer to the thread object from the passed thread ID.

\n

Reference: PsLookupThreadByThreadId function (ntifs.h) - Windows drivers | Microsoft Docs

\n

PsLookupThreadByThreadId can be used by including ntifs.h.

\n

To avoid compile errors, ntifs.h needs to be included before ntddk.h.

\n

Let’s look at the code.

\n
PETHREAD Thread;\nstatus = PsLookupThreadByThreadId(ULongToHandle(data->ThreadId), &Thread);\nif (!NT_SUCCESS(status)) break;\n\nKeSetPriorityThread((PKTHREAD)Thread, data->Priority);\nObDereferenceObject(Thread);\nKdPrint(\n    (\"Thread Priority change for %d to %d succeeded!\\n\",\n      data->ThreadId, data->Priority\n    )\n);\nbreak;
\n

After setting the priority, the ObDereferenceObject macro is called.

\n

This macro decrements the reference count of the object passed as an argument, but I did not quite understand what it was for.

\n

Reference: ObDereferenceObject macro (wdm.h) - Windows drivers | Microsoft Docs

\n

A reference count seems to be a count of how many references or pointers to that object exist within the system.

\n

If the reference count is 0, the system (perhaps GC or something similar) is allowed to destroy it.

\n

Reference: Reference counting - Wikipedia

\n

The reason ObDereferenceObject decrements the reference count here is to prevent leaks in the system.

\n

PsLookupThreadByThreadId increments the reference count for the thread it receives.

\n

Therefore, if it is not decremented by ObDereferenceObject before the routine finishes, the reference count remains increased and a leak occurs.

\n

With that, I was able to trace through the kernel driver implementation more or less all the way through.

\n

I will omit the client implementation in this article.

\n

If you want to dig into it in more detail, please purchase Windows Kernel Driver Programming.

\n

Installing the driver

\n

As in the previous article, install the created driver into the system using the same procedure.

\n
$ sc create second type= kernel binPath= C:\\Driver\\SecondDriver\\SecondDriver.sys\n[SC] CreateService SUCCESS\n\n$ sc start second\nSERVICE_NAME: second\n        TYPE               : 1  KERNEL_DRIVER\n        STATE              : 4  RUNNING\n                                (STOPPABLE, NOT_PAUSABLE, IGNORES_SHUTDOWN)\n        WIN32_EXIT_CODE    : 0  (0x0)\n        SERVICE_EXIT_CODE  : 0  (0x0)\n        CHECKPOINT         : 0x0\n        WAIT_HINT          : 0x0\n        PID                : 0\n        FLAGS              :
\n

After this, if you check GLOBAL?? in WinObj, you can confirm that the symbolic link for the SecondDriver you created exists.

\n

\n \n \n \n \n \n \n \n \n

\n

Now that the driver has been installed, let’s try setting a thread’s priority with the client application.

\n

This time, for verification, I decided to manipulate a Notepad thread.

\n

From Proexp, you can see that the Notepad thread’s priority is set to 10.

\n

\n \n \n \n \n \n \n \n \n

\n

Let’s set this thread to the maximum priority, 31.

\n
C:\\Driver\\SecondDriverClient.exe 8616 31
\n

After the application finishes executing, the Notepad thread’s priority changes to 31 as shown below.

\n

\n \n \n \n \n \n \n \n \n

\n

This time, to do something a little different from before, I decided to analyze it mainly through the GUI.

\n

Once execution reaches the line immediately after the stack location is obtained, inspect the stack location information in the Locals window.

\n

In WinDbg’s GUI, the structure information can be formatted and inspected like this.

\n

\n \n \n \n \n \n \n \n \n

\n

The arguments passed from the application are stored in the input buffer of the IRP passed to the device control routine.

\n

If you inspect the location pointed to by the input buffer, you can see that it is 0x1cefd9f6d8.

\n

\n \n \n \n \n \n \n \n \n

\n

So, let’s look at the values stored at that referenced address in the Memory window.

\n

\n \n \n \n \n \n \n \n \n

\n

In the client application, the received arguments are converted into numeric values with the atoi function and then passed to the driver routine as follows.

\n
data.ThreadId = atoi(argv[1]);\ndata.Priority = atoi(argv[2]);
\n

The C++ atoi function converts a string into a 4-byte int value.

\n

Therefore, it seems best to read the data stored in memory in little-endian format, 4 bytes at a time.

\n

From the above, we can see that the values stored in the memory pointed to by the input buffer match the arguments given to the client application, as follows.

\n
0x2148 = 8520\n0x1F = 31
\n

WinDbg makes it very easy to inspect the IRP information passed to a kernel driver, which is extremely convenient.

\n

Summary

\n

Now I have been able to get an introductory look at implementing a kernel driver with the minimum necessary functionality, as well as analyzing IRPs through debugging.

\n

There is still a long way to go, but I plan to keep studying kernel programming and debugging.

\n

Reference books

\n","fields":{"slug":"/windows-windriver-002-irp-en","tagSlugs":["/tag/win-dbg/","/tag/kernel/","/tag/kernel-driver/","/tag/reversing/","/tag/english/"]},"frontmatter":{"date":"2022-01-29","description":"","tags":["WinDbg","Kernel","KernelDriver","Reversing","English"],"title":"Writing a Windows Kernel Driver from Scratch and Inspecting IRP Requests with WinDbg","socialImage":{"publicURL":"/static/d540acb87fd7fe1b60f3feef78deb15c/windows-windriver-002-irp.png"}}}},"pageContext":{"slug":"/windows-windriver-002-irp-en"}},"staticQueryHashes":["251939775","401334301","825871152"]}