Função IoCreateSystemThread (wdm.h)

Artigo
03/08/2023

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

Sintaxe

NTSTATUS IoCreateSystemThread(
  [in, out]       PVOID              IoObject,
  [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

[in, out] IoObject

Um ponteiro para o DEVICE_OBJECT ou DRIVER_OBJECT para associar ao thread criado. IoCreateSystemThread faz uma referência contada a esse objeto. O gerenciador de E/S posteriormente libera essa referência quando o thread é encerrado. Para obter mais informações, consulte Comentários.

[out] ThreadHandle

Um ponteiro para uma variável na qual a rotina grava o identificador de kernel para o thread criado. Quando o identificador não for mais necessário, o driver deverá fechar o identificador chamando a rotina ZwClose .

[in] DesiredAccess

O valor ACCESS_MASK que representa os tipos de acesso às solicitações de chamador para o thread criado.

[in, optional] ObjectAttributes

Um ponteiro para uma estrutura OBJECT_ATTRIBUTES que especifica os atributos do objeto thread. Os atributos OBJ_PERMANENT, OBJ_EXCLUSIVE e OBJ_OPENIF não são atributos válidos para um objeto thread. Se o chamador não estiver em execução no contexto do processo do sistema, ele deverá definir o atributo OBJ_KERNEL_HANDLE na estrutura OBJECT_ATTRIBUTES .

[in, optional] ProcessHandle

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

[out, optional] ClientId

Um ponteiro para uma estrutura na qual a rotina grava o identificador do cliente para o thread criado. Esse parâmetro deve ser NULL para um thread criado pelo driver.

[in] StartRoutine

Um ponteiro para uma rotina ThreadStart que é o ponto de entrada para o thread criado.

[in, optional] StartContext

Um ponteiro de contexto que é passado como o parâmetro StartContext para a rotina ThreadStart quando o thread criado começa a ser executado.

Retornar valor

IoCreateSystemThread retornará STATUS_SUCCESS se o novo thread tiver sido criado com êxito. Os possíveis valores retornados incluem o seguinte erro status códigos.

Código de retorno	Descrição
STATUS_INVALID_HANDLE	ProcessHandle não é um identificador de processo válido.
STATUS_PROCESS_IS_TERMINATING	O processo especificado pelo ProcessHandle está sendo encerrado.
STATUS_INSUFFICIENT_RESOURCES	Recursos insuficientes do sistema estão disponíveis para executar a operação solicitada.

Comentários

Começando com Windows 8, um driver pode chamar IoCreateSystemThread para criar um thread dedicado ao dispositivo. Essa rotina cria um novo thread do sistema que não tem nenhum bloco de ambiente de thread (TEB) ou contexto de modo de usuário e é executado somente no modo kernel.

Normalmente, o driver chama IoCreateSystemThread quando inicia o dispositivo ou quando as rotinas de Expediçãoxxx do driver começam a receber solicitações de E/S. Por exemplo, um driver pode chamar essa rotina para criar um thread quando uma rotina DispatchXxx recebe uma solicitação de controle de dispositivo assíncrona.

Se o parâmetro ProcessHandle 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 seja encerrado.

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 IoCreateSystemThread. Esse atributo restringe o uso do identificador retornado por IoCreateSystemThread 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 chamar a macro InitializeObjectAttributes para definir o atributo OBJ_KERNEL_HANDLE nos atributos de objeto, conforme mostrado no exemplo de código a seguir.

OBJECT_ATTRIBUTES ObjectAttributes;

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

IoCreateSystemThread é semelhante à rotina PsCreateSystemThread , mas tem um parâmetro adicional, IoObject, que é um ponteiro para o objeto de driver ou objeto do dispositivo do chamador. IoCreateSystemThread usa esse parâmetro para garantir que o driver não possa descarregar enquanto o thread criado existir. Antes de agendar StartRoutine para execução neste thread, IoCreateSystemThread usa uma referência contada ao objeto IoObject . O gerenciador de E/S libera essa referência após a saída do thread criado. Portanto, esse objeto persiste durante o tempo de vida do thread criado.

Em contraste com um thread do sistema criado pela rotina PsCreateSystemThread , um thread criado por IoCreateSystemThread não chama a rotina PsTerminateSystemThread para terminar sozinho. Em vez disso, o gerente de E/S chama PsTerminateSystemThread em nome do thread criado quando o thread é encerrado.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Disponível a partir do Windows 8.
Plataforma de Destino	Universal
Cabeçalho	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
Biblioteca	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL