PsCreateSystemThread function (wdm.h)

Article
02/28/2023

The PsCreateSystemThread routine creates a system thread that executes in kernel mode and returns a handle for the thread.

Syntax

NTSTATUS PsCreateSystemThread(
  [out]           PHANDLE            ThreadHandle,
  [in]            ULONG              DesiredAccess,
  [in, optional]  POBJECT_ATTRIBUTES ObjectAttributes,
  [in, optional]  HANDLE             ProcessHandle,
  [out, optional] PCLIENT_ID         ClientId,
  [in]            PKSTART_ROUTINE    StartRoutine,
  [in, optional]  PVOID              StartContext
);

Parameters

[out] ThreadHandle

Points to a variable that will receive the handle. The driver must close the handle with ZwClose once the handle is no longer in use. This handle is a kernel handle for Windows Vista and later versions of Windows. In earlier versions of Windows, the handle might not be a kernel handle.

[in] DesiredAccess

Specifies the ACCESS_MASK value that represents the requested types of access to the created thread.

[in, optional] ObjectAttributes

Points to a structure that specifies the object's attributes. OBJ_PERMANENT, OBJ_EXCLUSIVE, and OBJ_OPENIF are not valid attributes for a thread object. On Windows XP and later versions of Windows, if the caller is not running in the system process context, it must set the OBJ_KERNEL_HANDLE attribute for ObjectAttributes. Drivers for Microsoft Windows 2000 and Windows 98/Me must only call PsCreateSystemThread from the system process context. For Windows Vista and later versions of Windows, the handle will be a kernel handle.

[in, optional] ProcessHandle

Specifies an open handle for the process in whose address space the thread is to be run. The caller's thread must have PROCESS_CREATE_THREAD access to this process. If this parameter is not supplied, the thread will be created in the initial system process. This value should be NULL for a driver-created thread. Use the NtCurrentProcess macro, defined in Ntddk.h, to specify the current process.

[out, optional] ClientId

Points to a structure that receives the client identifier of the new thread. This value should be NULL for a driver-created thread.

[in] StartRoutine

The entry point for the newly created system thread. This parameter is a function pointer to a ThreadStart routine that receives a single argument, which is the StartContext parameter value supplied by the caller.

[in, optional] StartContext

Supplies a single argument that is passed to the thread when it begins execution.

Return value

PsCreateSystemThread returns STATUS_SUCCESS if the thread was created.

Remarks

Drivers that create device-dedicated threads call this routine, either when they initialize or when I/O requests begin to come in to such a driver's Dispatch routines. For example, a driver might create such a thread when it receives an asynchronous device control request.

PsCreateSystemThread creates a kernel-mode thread that begins a separate thread of execution within the system. Such a system thread has no TEB or user-mode context and runs only in kernel mode.

If the input ProcessHandle is NULL, the created thread is associated with the system process. Such a thread continues running until either the system is shut down or the thread terminates itself by calling PsTerminateSystemThread.

Driver routines that run in a process context other than that of the system process must set the OBJ_KERNEL_HANDLE attribute for the ObjectAttributes parameter of PsCreateSystemThread. This restricts the use of the handle returned by PsCreateSystemThread to processes running in kernel mode. Otherwise, the thread handle can be accessed by the process in whose context the driver is running. Drivers can set the OBJ_KERNEL_HANDLE attribute as follows.

InitializeObjectAttributes(&ObjectAttributes, NULL, OBJ_KERNEL_HANDLE, NULL, NULL);

For more information about the StartContext parameter, see ThreadStart.

The newly created system thread runs at PASSIVE_LEVEL inside a critical region with normal kernel APCs disabled.

Requirements

Requirement	Value
Target Platform	Universal
Header	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
Library	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
DDI compliance rules	HwStorPortProhibitedDDIs(storport), IrqlPsPassive(wdm)