Função PsCreateSystemThread (wdm.h)

Artigo
03/08/2023

A rotina PsCreateSystemThread cria um thread do sistema que é executado no modo kernel e retorna um identificador para o thread.

Sintaxe

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
);

Parâmetros

[out] ThreadHandle

Aponta para uma variável que receberá o identificador. O driver deve fechar o identificador com ZwClose depois que o identificador não estiver mais em uso. Esse identificador é um identificador de kernel para Windows Vista e versões posteriores do Windows. Em versões anteriores do Windows, o identificador pode não ser um identificador de kernel.

[in] DesiredAccess

Especifica o valor ACCESS_MASK que representa os tipos de acesso solicitados ao thread criado.

[in, optional] ObjectAttributes

Aponta para uma estrutura que especifica os atributos do objeto. OBJ_PERMANENT, OBJ_EXCLUSIVE e OBJ_OPENIF não são atributos válidos para um objeto thread. No Windows XP e versões posteriores do Windows, se o chamador não estiver em execução no contexto do processo do sistema, ele deverá definir o atributo OBJ_KERNEL_HANDLE para ObjectAttributes. Os drivers para Microsoft Windows 2000 e Windows 98/Me só devem chamar PsCreateSystemThread no contexto do processo do sistema. Para o Windows Vista e versões posteriores do Windows, o identificador será um identificador de kernel.

[in, optional] ProcessHandle

Especifica um identificador aberto para o processo em cujo espaço de endereço o thread deve ser executado. O thread do chamador deve ter PROCESS_CREATE_THREAD acesso a esse processo. Se esse parâmetro não for fornecido, o thread será criado no processo inicial do sistema. Esse valor deve ser NULL para um thread criado pelo driver. Use a macro NtCurrentProcess , definida em Ntddk.h, para especificar o processo atual.

[out, optional] ClientId

Aponta para uma estrutura que recebe o identificador de cliente do novo thread. Esse valor deve ser NULL para um thread criado pelo driver.

[in] StartRoutine

O ponto de entrada para o thread do sistema recém-criado. Esse parâmetro é um ponteiro de função para uma rotina ThreadStart que recebe um único argumento, que é o valor do parâmetro StartContext fornecido pelo chamador.

[in, optional] StartContext

Fornece um único argumento que é passado para o thread quando ele inicia a execução.

Retornar valor

PsCreateSystemThread retornará STATUS_SUCCESS se o thread tiver sido criado.

Comentários

Os drivers que criam threads dedicados ao dispositivo chamam essa rotina, seja quando inicializam ou quando as solicitações de E/S começam a entrar nas rotinas de Expedição desse driver. Por exemplo, um driver pode criar esse thread quando recebe uma solicitação de controle de dispositivo assíncrona.

PsCreateSystemThread cria um thread no modo kernel que inicia um thread separado de execução dentro do sistema. Esse thread do sistema não tem nenhum contexto de modo de usuário ou TEB e é executado somente no modo kernel.

Se o ProcessHandle de entrada for NULL, o thread criado será associado ao processo do sistema. Esse thread continua em execução até que o sistema seja desligado ou o thread termine sozinho chamando PsTerminateSystemThread.

As rotinas de driver executadas em um contexto de processo diferente do processo do sistema devem definir o atributo OBJ_KERNEL_HANDLE para o parâmetro ObjectAttributes de PsCreateSystemThread. Isso restringe o uso do identificador retornado por PsCreateSystemThread a processos em execução no modo kernel. Caso contrário, o identificador de thread pode ser acessado pelo processo em cujo contexto o driver está em execução. Os drivers podem definir o atributo OBJ_KERNEL_HANDLE da seguinte maneira.

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

Para obter mais informações sobre o parâmetro StartContext , consulte ThreadStart.

O thread do sistema recém-criado é executado em PASSIVE_LEVEL dentro de uma região crítica com APCs de kernel normais desabilitadas.

Requisitos

Requisito	Valor
Plataforma de Destino	Universal
Cabeçalho	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
Biblioteca	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
Regras de conformidade da DDI	HwStorPortProhibitedDDIs(storport), IrqlPsPassive(wdm)