PsCreateSystemThread, fonction (wdm.h)

Article
03/08/2023

La routine PsCreateSystemThread crée un thread système qui s’exécute en mode noyau et retourne un handle pour le thread.

Syntaxe

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

Paramètres

[out] ThreadHandle

Pointe vers une variable qui recevra le handle. Le pilote doit fermer la poignée avec ZwClose une fois que la poignée n’est plus utilisée. Ce handle est un handle de noyau pour Windows Vista et les versions ultérieures de Windows. Dans les versions antérieures de Windows, le handle peut ne pas être un handle de noyau.

[in] DesiredAccess

Spécifie la valeur ACCESS_MASK qui représente les types d’accès demandés au thread créé.

[in, optional] ObjectAttributes

Pointe vers une structure qui spécifie les attributs de l’objet. OBJ_PERMANENT, OBJ_EXCLUSIVE et OBJ_OPENIF ne sont pas des attributs valides pour un objet thread. Sur Windows XP et les versions ultérieures de Windows, si l’appelant n’est pas en cours d’exécution dans le contexte du processus système, il doit définir l’attribut OBJ_KERNEL_HANDLE pour ObjectAttributes. Les pilotes pour Microsoft Windows 2000 et Windows 98/Me doivent uniquement appeler PsCreateSystemThread à partir du contexte de processus système. Pour Windows Vista et les versions ultérieures de Windows, le handle est un handle de noyau.

[in, optional] ProcessHandle

Spécifie un handle ouvert pour le processus dans lequel le thread doit être exécuté. Le thread de l’appelant doit avoir PROCESS_CREATE_THREAD accès à ce processus. Si ce paramètre n’est pas fourni, le thread est créé dans le processus système initial. Cette valeur doit être NULL pour un thread créé par un pilote. Utilisez la macro NtCurrentProcess , définie dans Ntddk.h, pour spécifier le processus actuel.

[out, optional] ClientId

Pointe vers une structure qui reçoit l’identificateur client du nouveau thread. Cette valeur doit être NULL pour un thread créé par un pilote.

[in] StartRoutine

Point d’entrée du thread système nouvellement créé. Ce paramètre est un pointeur de fonction vers une routine ThreadStart qui reçoit un argument unique, qui est la valeur du paramètre StartContext fournie par l’appelant.

[in, optional] StartContext

Fournit un seul argument qui est passé au thread quand il commence l’exécution.

Valeur retournée

PsCreateSystemThread retourne STATUS_SUCCESS si le thread a été créé.

Remarques

Les pilotes qui créent des threads dédiés à l’appareil appellent cette routine, soit lorsqu’ils s’initialisent, soit lorsque les demandes d’E/S commencent à entrer dans les routines Dispatch d’un tel pilote. Par exemple, un pilote peut créer un tel thread lorsqu’il reçoit une demande de contrôle d’appareil asynchrone.

PsCreateSystemThread crée un thread en mode noyau qui commence un thread d’exécution distinct au sein du système. Un tel thread système n’a pas de contexte TEB ou en mode utilisateur et s’exécute uniquement en mode noyau.

Si l’entrée ProcessHandle a la valeur NULL, le thread créé est associé au processus système. Un tel thread continue de s’exécuter jusqu’à ce que le système soit arrêté ou que le thread se termine lui-même en appelant PsTerminateSystemThread.

Les routines de pilote qui s’exécutent dans un contexte de processus autre que celui du processus système doivent définir l’attribut OBJ_KERNEL_HANDLE pour le paramètre ObjectAttributes de PsCreateSystemThread. Cela limite l’utilisation du handle retourné par PsCreateSystemThread aux processus exécutés en mode noyau. Sinon, le handle de thread est accessible par le processus dans le contexte dans lequel le pilote est en cours d’exécution. Les pilotes peuvent définir l’attribut OBJ_KERNEL_HANDLE comme suit.

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

Pour plus d’informations sur le paramètre StartContext , consultez ThreadStart.

Le thread système nouvellement créé s’exécute à PASSIVE_LEVEL à l’intérieur d’une région critique avec les API de noyau normales désactivées.

Configuration requise

Condition requise	Valeur
Plateforme cible	Universal
En-tête	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
Bibliothèque	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
Règles de conformité DDI	HwStorPortProhibitedDDIs(storport), IrqlPsPassive(wdm)